Intial draft of installation guide

[chrisjsewell]

No description provided.

[chrisjsewell]

Some notes:

I wrote the install instructions whilst going through the process on a fresh Ubuntu VM (in csewell-test on CSCS OpenStack), which now works (after conda-forge/aiida-core-feedstock#31).
The extra steps around verdi quicksetup have also been previously discussed with @ltalirz e.g. in chrisjsewell/activate_aiida#1.

You might want to comment, since it feeds into the other discussion we've had e.g. in chrisjsewell/activate_aiida#1. Note that I wrote the install instructions whilst going through the process on a fresh Ubuntu VM (in csewell-test on CSCS OpenStack)

The next steps is intended to be reminiscent of:

• https://pandas.pydata.org/docs/getting_started/index.html#getting-started
• https://github.com/pandas-dev/pandas/blob/master/doc/source/getting_started/install.rst

Here they use a lot of raw HTML; for the panels and the "accordian" drop downs. Currently I have added sphinx-togglebutton as a stand-in, but ideally in the long run I think it would be worth investigating if these can be implemented as a "simple" sphinx directive extension.

[chrisjsewell]

Here they use a lot of raw HTML; for the panels and the "accordian" drop downs.

In 8d1806b I have added a simple directive for accordions, as opposed to using raw HTML (this could eventually be extracted to a separate repo).
@csadorf I can add one for the panels as well if you want

[chrisjsewell]

In c946c9f I've also added a panels directive. They look like this:

[ltalirz]

Thanks a lot @chrisjsewell !

The panels look great!
I see it requires a bit of extra python code but I'd be ok with this if we all agree that these panels are what we want.

As for using conda as the default route, I think there are some open questions that would be good to discuss with a broader audience.

[ltalirz]

"numerous routes" should probably be a link to the place where they are listed

[ltalirz]

While, until you arrived, I've been the guy in the AiiDA team pushing most for supporting the conda route, I still feel that before we make conda the default installation path we need a little more testing of this for production.
I guess, so far, you are the only one using the aiida-core coda package (? we should ask!).

Since the availability with python 3.6-3.8 has now been taken care of, my main remaining doubts are these:

1. In my experience, people are easily confused when mixing pip and conda installations of packages and the will need to use pip to install most of the plugins. How can we effectively mitigate this?
2. Do people prefer to have Postgresql & rabbitmq be a system service (that restarts when they restart their computer) or are they fine starting them manually every time?

I think we should discuss these two questions within the AiiDA team and, possibly, also in the plugin-developers github team.

And, if in the end we decide to go with conda, I'd be happy to integrate your aiida-active script in to the aiida.services package (or add a perhaps slightly reduced version of it as a dependency).

[chrisjsewell]

Yes certainly this requires a group decision. The main thing with Conda is that it works cross-platform, so in this "quick install" I don't have to complicate things with discussing the OS dependent installations of the services. Obviously there will also be the advanced/detailed installation section, where I will go in to more detail about the different routes to setting up the services.

In my experience, people are easily confused when mixing pip and conda installations of packages

What would you say exactly is the confusion? Do we just need to say that you can use pip within a conda environment?

[ltalirz]

What would you say exactly is the confusion? Do we just need to say that you can use pip within a conda environment?

I've often heard of problems with dependencies being overwritten by pip / conda when doing this (e.g. pip installs a different version of a dependency without conda being informed, etc.). This can be very nasty, up to the point where people no longer know how to fix the problem.

[chrisjsewell]

This can be very nasty, up to the point where people no longer know how to fix the problem.

Well just start again from a fresh environment 😉 Personally I have never had this problem, and the other thing is that it is very easy with Conda for people to share conda-env.yaml (which as you know can include conda and pip packages) containing version specifications that are known to be compatible.
But either way we should definitely be encouraging the use of isolated environments: e.g. https://medium.com/@krishnaregmi/pipenv-vs-virtualenv-vs-conda-environment-3dde3f6869ed

[ltalirz]

As for the drop-down stuff, we are already using something similar here
https://aiida.readthedocs.io/projects/aiida-core/en/latest/install/quick_installation.html#prerequisites

We should just decide which one we prefer; then we can drop one of the two implementations.

[chrisjsewell]

The panels look great!cI see it requires a bit of extra python code but I'd be ok with this if we all agree that these panels are what we want.

Ta, yes obviously it was easier to quickly code these up internally, but I could imagine extracting them into some packages in https://github.com/executablebooks at some point.

[chrisjsewell]

We should just decide which one we prefer; then we can drop one of the two implementations.

Yep my ones better 😉 I may also eventually fold my one in to executablebooks/sphinx-togglebutton#11

[chrisjsewell]

FYI another neat feature of note, is that the panels now adapt to small screens.

[chrisjsewell]

@csadorf in 3e506b9 I have updated the landing page:

[csadorf]

Replaced by aiidateam#4011