Update docs to AiiDA v2.x and Jupyter Book

[Irratzo]

This is an AiiDA-KKR improvements issue.

All references to repositories in this post are permalinks to latest commits at time of writing, for archival purposes.

The current documentation is out of date.

(One example: User's guide example uses length unit Angstroem, but kkrparams switched to length unit Bohr.)

((In more detail: JuKKR internally uses Bohr length units. AiiDA-KKR uses Angstrom units and converts as needed. For instance, the impurity_info Dict node assumes its properties Rcut to be given in Angstrom units, but Rimp_rel and imp_cls to be given in ALAT units. This info should be added to the impurity_info docs section. That is why, for instance, plot_kkr_imp_sub_wc converts back and forth with ALAT units.))

In addition, the plugin migration to AiiDA v2.x is finished.

In addition, the current docs source format is reStructuredText (RST). RST is good for technical documentation, but complex to use. The Executable Books Project has made writing such text simpler by creating both the MyST format (a Markdown flavor for technical writing, inspired by RST but simpler to use), and the possibility to write docs as Jupyter notebooks (.ipynb) (Jupyter Book). For example, the JuDFTteam masci-tools docs have switched to MyST, and chrisjsewell (AiiDA and Executable Books Project contributor) has created aiida-qe-demo, a tutorial based solely on Jupyter notebook source format. The latter has the additional feature supported by Jupyter Book projects that a docs page has a 'launch' button, allowing the reader to execute the respective page as a notebook directly from their browser in a computational environment without installation, like Binder or Google Colab.

So, this improvements issue has two aims.

1. Migrate the docs from RST to MyST, or Jupyter Book.
2. Update the docs contents from AiiDA v1.x to AiiDA v2.x

For subtask two, this means that the current docs will be the last version aimed at AiiDA-KKR used with AiiDA v1.x. We skip the subtask of first updating to docs to the current state of AiiDA-KKR used with AiiDA v1.x. (such as the initial example).

For subtask one, it is worthwhile to note that MyST / Jupyter Book -- based docs accept as source format either RST (.rst), MyST Markdown (.md), or Jupyter notebooks (.ipynb). Assisted conversion from RST to MyST is possible via the tool RST-to-MyST, and conversion (or, alternatively, local syncing between) MyST and Jupyter notebook is possible via the tool Jupytext. Both are mentioned in the Jupyter Book docs and MyST docs. At this point we have only decided to switch from RST to MyST or notebooks as source format, but not on the latter.

We will use the masci-tools and aiida-qe-demo docs as guiding examples.

An additional subtask is that aiida-kkr has an examples folder /examples, outside of the /docs, with Jupyter notebooks in various stages of outdatedness. These also should be integrated into the "new" docs.

Additional resources for using Jupyter Book for documentation:

• pytest-notebook for testing
• MyST-NB for converting notebooks to documentation

[Irratzo]

Created branch support/aiida-2.x-docs from branch support/aiida-2.X.

Commit commit 01 of improvement 'migrate docs to MyST'.

Ran RST-to-MyST converter on all docs at once, as described in its docs.

$ cd /opt/aiida-kkr/docs/source
$ rst2myst convert docs/**/*.rst

Result:

find . -name "*.rst"	find . -name "*.md"
./developer_guide/index.rst	./developer_guide/index.md
./index.rst	./index.md
./module_guide/calculations.rst	./module_guide/calculations.md
./module_guide/data.rst	./module_guide/data.md
./module_guide/index.rst	./module_guide/index.md
./module_guide/parsers.rst	./module_guide/parsers.md
./module_guide/tools.rst	./module_guide/tools.md
./module_guide/workflows.rst	./module_guide/workflows.md
./user_guide/calculations.rst	./user_guide/calculations.md
./user_guide/index.rst	./user_guide/index.md
./user_guide/tools.rst	./user_guide/tools.md
./user_guide/workflows.rst	FAILED
./user_guide/workfunctions.rst	./user_guide/workfunctions.md

Output:

$ rst2myst convert docs/source/**/*.rst
docs/source/developer_guide/index.rst -> docs/source/developer_guide/index.md
CONVERTED (extensions: ['colon_fence'])
docs/source/module_guide/calculations.rst -> docs/source/module_guide/calculations.md
CONVERTED (extensions: [])
docs/source/module_guide/data.rst -> docs/source/module_guide/data.md
CONVERTED (extensions: [])
docs/source/module_guide/index.rst -> docs/source/module_guide/index.md
CONVERTED (extensions: [])
docs/source/module_guide/parsers.rst -> docs/source/module_guide/parsers.md
CONVERTED (extensions: [])
docs/source/module_guide/tools.rst -> docs/source/module_guide/tools.md
CONVERTED (extensions: [])
docs/source/module_guide/workflows.rst -> docs/source/module_guide/workflows.md
CONVERTED (extensions: [])
docs/source/user_guide/calculations.rst -> docs/source/user_guide/calculations.md
source:83: (WARNING/2) Explicit markup ends without a blank line; unexpected unindent.
source:167: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
source:454: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
CONVERTED (extensions: ['deflist', 'colon_fence'])
docs/source/user_guide/index.rst -> docs/source/user_guide/index.md
CONVERTED (extensions: [])
docs/source/user_guide/tools.rst -> docs/source/user_guide/tools.md
CONVERTED (extensions: ['colon_fence'])
docs/source/user_guide/workflows.rst -> docs/source/user_guide/workflows.md
source:484: (SEVERE/4) Title level inconsistent:

Example Usage:
^^^^^^^^^^^^^^
FAILED:
source:484: (SEVERE/4) Title level inconsistent:

Example Usage:
^^^^^^^^^^^^^^
docs/source/user_guide/workfunctions.rst -> docs/source/user_guide/workfunctions.md
CONVERTED (extensions: ['deflist', 'colon_fence'])

FINISHED ALL! (extensions: ['deflist', 'colon_fence'])

TODO:

• Fix cause for conversion FAIL in ./user_guide/workflows.rst and run again.