Docs: add "How to - Configuring your installation"

[sphuber]

Fixes #4001

This section describes how multiple instances of AiiDA can be isolated
on the same machine, how tab-completion can be activated and how the
verdi config command can be used to configure profile options.

Except for the verdi config section, which is completely new, the
other content has been adapted from existing documentation.

[sphuber]

Two things here:

1. In the "Isolating multiple instances" section, should there be a link to more detailed information on how to work with virtual environments? I feel that we should not be responsible for explaining this concept, and certainly not in this how-to section, but on the other hand I fear this section maybe difficult to understand for people that have never even heard of a virtual environment. Then again, would those be the kind of people to read this section?
2. I have the slight feeling that this how-to should actually come before the "Managing profiles" of PR Docs: add "How to manage your installation - Managing profiles" #4066

[greschd]

I think it should be mentioned somewhere that using the same code (virtualenv) for different .aiida folders works perfectly fine, while the opposite (multiple code versions running on the same .aiida folder) is bound to lead to problems.

[sphuber]

I think it should be mentioned somewhere that using the same code (virtualenv) for different .aiida folders works perfectly fine, while the opposite (multiple code versions running on the same .aiida folder) is bound to lead to problems.

Good point. This is more or less implied by the later detailed explanation that the AIIDA_PATH can support multiple paths, correct. Should I add your comment there in a .. note:: perhaps?

[csadorf]

I've made various suggestions for improving the style of this section and fixed a few errors, but content looks overall fine to me.

[csadorf]

Does the .. important:: directive require two empty lines surrounding it?

[sphuber]

It doesn't require anything different from the other markup marks such as .. note:: but I see just a single empty line. Did you mean two linebreaks? I personally like the empty line for readability, but happy to change. What would the standard be? Directly following the mark, or a single linebreak? I guess the former would become problematic if the note contains multiple sentences. So I would vote for either 1 or 2 linebreaks

[sphuber]

@csadorf what do you think about my question regarding the order of this section and that of my other PR. Would you agree that it makes sense to swap the current order and put this one first and the "Managing profiles" second?

[csadorf]

@csadorf what do you think about my question regarding the order of this section and that of my other PR. Would you agree that it makes sense to swap the current order and put this one first and the "Managing profiles" second?

I think it depends on what we consider a more widely applicable scenario:

1. Having multiple software installations.
2. Using multiple profiles.

I'm assuming it's #1 for the expert user and #2 for the average user, what do you think?

[sphuber]

I'm assuming it's #1 for the expert user and #2 for the average user, what do you think?

This is the problem though, #1 is not necessarily just for expert users. Since we always recommend the use of virtual environments, the information of the AIIDA_PATH is also pertinent to those situations, even though there is just a single instance of AiiDA.

There is even a comment from a user on #4001 that suggest that this information should be close to the installation. I am not convinced that we should, but it does show that it might be valuable information also for starting users with a single instance.

Of course, not knowing about AIIDA_PATH will just use the standard location, so thinking about it, a beginning user does not need to know about it, so maybe we shouldn't. I guess the current order is fine then.

[csadorf]

@sphuber I think you misunderstood my comment. I did not want to imply that #1 is only applicable for expert aiida users nor that #2 is only applicable to average aiida users. What I'm asking is: which scenario you are more likely to encounter as the average user? That should drive the order of these two sections.

[sphuber]

@csadorf I see. Well, I guess parts of part 2 (enabling tab-completion and verdi config) are just as useful for beginning users as part 1. But the part on having isolating multiple environments is actually more for experienced users. So maybe there is even a problem in structure within part 2. I guess I can just move those two sub parts to the beginning since they don't depend at all on the isolation of environments part.

[csadorf]

One more question, otherwise good to go.

[csadorf]

I'm a bit confused by this warning. Why do I need to worry about this?

Would the following warning be correct?

Suggested change

	If there was no ``.aiida`` directory in ``~/project_a``, AiiDA would have created it for you, so make sure to set the ``AIIDA_PATH`` correctly.
	AiiDA will create the ``.aiida`` directory in ``~/project_a`` in case that it does not exist yet.

Or is the warning related to the fact that it will create the complete path and not only the .aiida/ leaf?

[sphuber]

The "problem" is that AiiDA will create the folder silently if it does not exist and will not raise an error. If a user, by accident, specifies the wrong path, the folder will be created in a different path then expected. Not that this will have grave consequences but it might be unexpected.