Guide to set up a new profile

[mkotiuga]

I recently set up my second profile (different project), and it took me quite a while to remember all the "set up" steps I needed to make the profile really operational (i.e. set up a computer, configure to the user, set up a code)

A quick "checklist" on the aiida-core documentation could be very useful and make the process of adding a profile more user-friendly. All the information is in the "getting started section", but this section is quite long and a lot to read when you just need to be reminded of a few key steps.

[giovannipizzi]

@ramirezfranciscof to be kept into the list of issues to discuss for tagging as a milestone in upcoming release

[unkcpz]

maybe it is better to have a verdi command which can export setup files for profile, code and computer? so that user can store the file in his computer and quickly setup new environment by simply change a few options in yaml config file then setup from it.

[giovannipizzi]

This is a good option.
Maybe we could have a verdi code export_all command, that exports in two possible formats (directly in .aiida, or in yaml).
In the first case, one would simply reimport the .aiida file (then, it would be useful to have a second script to identify the unconfigured computers that were just imported and run verdi computer configure on (a subset of) them. This is mostly useful when a user is creating a new profile, but has access to all machines and codes.

The yaml is instead interesting to give to someone else to adapt.

If we converge to how the interface should work, we can implement it.

[ramirezfranciscof]

@ramirezfranciscof to be kept into the list of issues to discuss for tagging as a milestone in upcoming release

Should I maybe create a tag for these? This could simplify tracking them rather than keeping a list somewhere else.

[giovannipizzi]

Sure. You mean a label? No problem of labelling them, but with care to avoid proliferation of labels.
E.g. use 'topic/xxx' for a given topic, checking it does not exist already with a different name, etc.
We have the milestones for things that should go in the next release.
You can still create a label for things to consider in a potential next release, to be then discussed (but be careful that, by experience, this ends up being very long and containing most of the issues, so one should already be a bit picky when labelling things :-) ).

[sphuber]

maybe it is better to have a verdi command which can export setup files for profile, code and computer? so that user can store the file in his computer and quickly setup new environment by simply change a few options in yaml config file then setup from it.

Note that there already is an open feature request for this. I started implementing it, but even though the concept is simple enough, the way the various data is currently stored in AiiDA, writing a maintainable and understandable implementation without a lot of hard coding is not trivial. I ended up having to refactor a lot of the Computer code and even had a PR, but I abandoned it, seeing that it needed much more thought first.

[sphuber]

Maybe we could have a verdi code export_all command, that exports in two possible formats (directly in .aiida, or in yaml).
In the first case, one would simply reimport the .aiida file (then, it would be useful to have a second script to identify the unconfigured computers that were just imported and run verdi computer configure on (a subset of) them. This is mostly useful when a user is creating a new profile, but has access to all machines and codes.

We already have the possibility to setup from yaml for profiles, computers and codes. I don't think adding much more functionality will address the problem that @mkotiuga highlighted. She was mostly looking for a place in the documentation to remind one that one should setup a profile, computer and code, before one can start working. The one problem here is that this does not apply to all use cases. Yes, a profile is required no matter what, but you can use AiiDA just fine without every setting up a computer or a code. It might not be the most common use case for our current users but we should be careful not to cater to only one specific use case.

[ltalirz]

I guess the docs revamp happened after this issue was opened.
We now have a dedicated how-to section on running an external code https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/index.html

Unless there are objections, I suggest we close this issue

[ramirezfranciscof]

@ltalirz that is a good observation, I agree we should review if this is ready to be closed. @mkotiuga: if you have the time, could you go a bit over the section (this is the direct link to what Leo is talking about) and give us some feedback regarding the content: was this what you were expecting? is there anything lacking? do you have any ideas on how it could be improved?

[mkotiuga]

Thanks, @ltalirz this page does cover all the steps to get a calculations with an external code up an running. I think this looks good. Coming back to my original issue - a checklist - is provided in the right panel. I'm not sure why, but I have noticed in using this new documentation that I do not notice that right panel sometimes - maybe the formatting. Furthermore, if your window is too narrow it disappears (this can be the case when I am working JUST on my laptop). For reference: on my macbook, my firefox window has to be the width of my screen -1cm to get this right side panel.

On other pages, I have found this right-side panel very useful for navigating the specific page, but again sometimes it takes me a while to notice it or my window is too narrow. (I think I notice it as current-section highlighting changes as I scroll.) Perhaps, this outline could be incorporated into the left-hand panel? I understand the right-hand panel is always "on this page" but its unfortunate it if is not there at all due to screen size.

Generally, I like the new documentation, but it can take me a while to find the page I was looking for. I end up bouncing between the "How-To", "Topics" and "Reference" - but this is probably for a new issue.

[chrisjsewell]

if your window is too narrow it disappears

@mkotiuga this is the desktop-to-mobile transition (they are hardcoded to particular screen pixel widths).
If you have any issues/questions on the HTML theme (which this is), I would suggest opening an issue on https://github.com/pandas-dev/pydata-sphinx-theme (I'm semi-involved with that project, so any feedback is appreciated)

but it can take me a while to find the page I was looking fo

Certainly if there are any pages/sections that you think should be more easily "findable" for users, let us know 😄

[giovannipizzi]

I also second the fact that the right panel is not in the place people expect it to be.
I think it's important to find a practical solution to this, also for me sometimes it's hard to realise that I should first click on the left, then further filter on the right, and then read on the centre... it's not the typical UX I would expect.

[chrisjsewell]

it's not the typical UX I would expect.

Well its the same UX as sites like Microsoft uses: https://code.visualstudio.com/docs, plus all the users of pydata-sphinx-theme and https://github.com/executablebooks/jupyter-book.
So I'm not sure I quite agree with that 😉

[giovannipizzi]

Ok - maybe people will get used to it if this is starting to get used.

Still, we don't have enough statistics to decide, but we shouldn't dismiss (on both sides, i.e. also including me I shouldn't force it) based only on personal taste.

We have at the moment at least two users (Michele and me) who don't find it super-intuitive.
Unless it's clear that we're the only two, I think we should investigate this more - ideally by asking people outside of the aiida team to search for something in the docs (that maybe we know involves use of the right menu) and get a feedback on what was or was not intuitive

[mkotiuga]

As the conversation has shifted from the original issue, maybe this issue should be closed and a new one on documentation layout and navigation should be opened?

[sphuber]

OK I am closing this, if people want to open a new issue about the layout, please go ahead