Docs: revamp Intro/Install

[chrisjsewell]

closes #4026
closes #4056

[chrisjsewell]

Ok this is coming along @csadorf, if you want a quick look!
A few notes:

• I've, at least temporarily, added a CircleCI config and added it to my account, as discussed in Docs: Consider using CircleCI for documentation CI #4028, this means you can directly view the built documentation 😁 https://17-145482568-gh.circle-artifacts.com/0/html/index.html
• I've dropped the accordion extension code, since it's now moved to sphinx-panels (as dropdown) @greschd you may be interested to note that this now uses the details HTML, just with fancy CSS, so no javascript 😄
• I've added a section on Docker installation and running. In lieu of using Binder its a pretty good alternative for people to use for the tutorials I think (I've removed mention of Binder for now, since we haven't set it up)
• There is a section on Updating from 0.12.* to 1.* and Breaking changes from 0.12.* to 1.*. I have moved this to an "orphan" document (breaking_changes.rst), i.e. it is not referenced in the ToC, and just include a link to it in the Updating aiida-core section.
• This doesn't cover the What is AiiDA page (Docs: intro/what is aiida #4024), which still needs work, and also isn't referenced in the front page
• the next steps on the getting started page are currently not filled in (perhaps open another issue for this).

[chrisjsewell]

One thing I've just realised, is that there is no top-level headers for any of the sections (tutorial, how-tos, topics, etc), and so nothing specific to link to on the front page!
Unless we introduce section index pages, I guess I can either link to the first page of each section.

[sphuber]

@chrisjsewell Just a thing I noticed just now: the sixth panel is called "Development" and describes that this is for guidelines for contributors, but we decided that this would be hosted on the Github wiki. Instead we have the "Internal Architecture" section. This will provide detailed information on the design and architecture and the reason behind it, including the decision process.

[chrisjsewell]

@sphuber does this look ok: https://69-77234579-gh.circle-artifacts.com/0/html/index.html

[csadorf]

Overall good, just a few minor suggestions.

[csadorf]

@sphuber Can we qualify this further?

[sphuber]

Not sure, to be honest. Depends on how how strict we want to have "tested" mean. If that should only include with what we have tested through CI, we should technically only list 18.04. If we want to be a bit more lenient, we could add 16.04 and Mac OS X, as we know people how have run successfully on it or are currently running on it. However, this might be a slippery slope, because for what versions of AiiDA does this hold? When do we remove a platform if it has not been tested in a long time. Do we add WSL, since we have some people that have run on it? This for example I don't think we should officially mention.

[csadorf]

Well we are mentioning WSL pretty extensively as a "supported installation method". I think we should have a brief team discussion about this at the next meeting and then we can make sure to consistently qualify what is considered a "supported system".

[csadorf]

I think I'd prefer to split this into "Install with pip (and venv)" and "Install with conda" instead of mixing the two things like this.

[chrisjsewell]

Fixed in 9323e43.
I haven't split into sections, because that doesn't make sense IMO, since you can also install with pip in a Conda environment. Virtual environments are covered in the section above, I've just clarified that it's installing from anaconda cloud and added the console line command

[csadorf]

There are limitations to using conda and pip in combination. Especially using conda with venv is not possible afaik or at least unwise in so far I think that the current structure is sub-optimal. So, while I disagree with you on this matter, I'm ok with leaving this for now, I don't think that this discussion should block this PR.

As a side note: I'd prefer if you could not resolve conversations that are not obviously resolved. Otherwise it is very difficult for me to follow open points for discussion, because I need to manually unhide all resolved conversations to check the status of the discussion.

[chrisjsewell]

Well it was resolved IMO 😉, but yeh I understand.

Especially using conda with venv is not possible afaik

pip has nothing to do with venv though:

1. you use venv, pipenv, or conda to create your virtual environment, then
2. within that virtual environment you use either pip, anaconda cloud (i.e. conda install), or git directly to install your python packages.

It would make absolutely no sense to create a venv inside conda, but using pip is absolutely fine (although using anaconda cloud is generally better for handling version dependencies)

[sphuber]

Hi @chrisjsewell , just a quick reminder that we all get emails for each commit made to this PR. So far I have received more than a 100 emails for this PR alone. If possible, it would be nice to try and limit the amount of commits that are pushed

[chrisjsewell]

Sorry @sphuber 😳 I'm basically done on this now! (you know that you can unsubscribe from the PR though 😬 )

[csadorf]

Just three minor suggestions, but otherwise I think this is ready!

[csadorf]

Hi @chrisjsewell , just a quick reminder that we all get emails for each commit made to this PR. So far I have received more than a 100 emails for this PR alone. If possible, it would be nice to try and limit the amount of commits that are pushed

@sphuber I think you should adjust your notification settings. I've been working with https://github.com/notifications which works very well in staying on top of mentions, PR requests, etc. Receiving a notification (and especially an email) with every commit is unreasonable IMO.

@chrisjsewell However, I think we should still try to bundle our commits (pushes) a little bit to reduce the strain on our CI resources.

[chrisjsewell]

I think we should still try to bundle our commits (pushes) a little bit to reduce the strain on our CI resources.

Yep absolutely 👍

[csadorf]

Ready to ship! 👍 Thank's a lot for this! 🎉