Docs: Rewrite the documentation

[sphuber]

Fixes #645

The documentation has been due for an overhaul for a long time. Many of the instructions still reference the API of AiiDA v0.x. In addition, the structure left much to be desired. Instead of just adjusting code here and there. The documentation is recreated from scratch. It adopts a similar structure as that of aiida-core which is a proven structure for documentation.

[sphuber]

Ok @mbercx I added the changes as discussed:

• Moved the removal of tcod related code to a separate PR and merged it. Didn't want that to get drowned out in this PR.
• Restored your beloved and beautiful logo in the docs landing page. Unfortunately, it doesn't really work in the header due to its aspect ratio.
• Updated the pw.x how-to to start with simple example
• Added the ph.x how-to

The script added for ph.x is also tested through the new integration job. However, there was a difficulty here as the script has a placeholder that should be replaced with the pk of a parent PwCalculation. This needed to somehow get updated in the script that runs the scripts, which I managed to do, but it is not the cleanest. Still, for now I think it is good to keep. I wonder if the notebook approach would simplify this, but I am not sure, as there the snippets just for ph will still not be independent and rely on the pw snippets (from another page) having been executed first. Or you would have to update the script to first run an entire pw calculation just for that, but that is something I think we should try to avoid as it will hurt the legibility of the ph script.

[mbercx]

Suggested edit:

diff --git a/docs/source/installation/index.rst b/docs/source/installation/index.rst
index b77ce38..8fc2e57 100644
--- a/docs/source/installation/index.rst
+++ b/docs/source/installation/index.rst
@@ -108,7 +108,7 @@ In this example, we will setup the ``localhost``, the computer where AiiDA itsel
 
         .. code-block:: console
 
-            verdi computer setup -n -L localhost -H localhost -T core.local -S core.direct
+            $ verdi computer setup -n -L localhost -H localhost -T core.local -S core.direct
 
         After creating the localhost computer, configure it using:
 

[mbercx]

Suggested edit:

diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst
index 55fcdd9..77ad032 100644
--- a/docs/source/tutorials/index.rst
+++ b/docs/source/tutorials/index.rst
@@ -230,7 +230,7 @@ A minimal setup to run an SCF calculation is shown below:
 
 .. note::
 
-    The ``pw.x`` code actually requires more input parameters then have been specified in the example above.
+    The ``pw.x`` code actually requires more input parameters than have been specified in the example above.
     The other required parameters are actually automatically defined by the ``PwCalculation`` plugin, based on for example the input structure.
     To find out what other parameters can be specified, please refer to the `documentation of Quantum ESPRESSO <https://www.quantum-espresso.org/Doc/INPUT_PW.html>`_.
     Note that certain parameters cannot be manually specified as these are reserved for the plugin to be set.

Would have been awesome if the "suggested edit" features of the VSCode extension actually resulted in suggestions as #848 (comment)

[mbercx]

Sorry, just playing around a bit with the VSCode pull request plugin ^^. Review is almost complete!

[mbercx]

Thanks a lot @sphuber! Great work, let's get this merged and then we can start adding more documentation from this fresh start. 🚀

Besides the comments below, I still wanted to make two remarks:

1. The content in the "Topics" still feels a lot more like a reference to me. What I imagine should go in the topics is a discussion on protocols etc. To be discussed.
2. There is of course some overlap between the tutorials here and in the aiida-core tutorials. We should think on how to make sure we don't have to maintain two sets of tutorials. Maybe we move the QE-related tutorials from the core tutorials here and then have the panel link to it?

[mbercx]

Best to add the command line prompt $ to console code blocks. Now the code is in italic. Note that our configuration is such that the prompt is not copied using the copy button.

[sphuber]

Would have thought that the console block would take care of this automatically. Maybe something to think of for in the future (also for aiida-core) that this role automatically adds this.

[sphuber]

Thanks for the review @mbercx

The content in the "Topics" still feels a lot more like a reference to me. What I imagine should go in the topics is a discussion on protocols etc. To be discussed.

Currently I would definitely agree, but my intention was that below the spec of the plugin we would provide in depth information about each input and how the plugin interacts with other plugins. I think that for such a discussion it might be very useful to start with a full overview of the spec which also functions as a table-of-contents at the same time. We could decide to move this to reference and then have each topic section include a link to that at the top. Would also work for me, maybe.

There is of course some overlap between the tutorials here and in the aiida-core tutorials. We should think on how to make sure we don't have to maintain two sets of tutorials. Maybe we move the QE-related tutorials from the core tutorials here and then have the panel link to it?

I think the tutorials here should be self-sufficient and focus on being as pragmatic as possible to get started with aiida-quantumespresso, linking to generic aiida-core tutorials for more generic AiiDA concepts. If the general AiiDA tutorials can simply reuse the tutorials, at least partially, that'd be great. They might add to them, for example more in the direction of data analysis once you have completed a bunch of calculations and workflows.

[mbercx]

All good, thanks @sphuber! We'll discuss the points above once I'm back from holiday. But for now this is already a vast improvement. 👍