commit 01 of improvement 'migrate docs to MyST': details ...

... result of running command 'rst2myst convert docs/source/**/*.rst' (auto-convert all rst to MyST md)

docs/source/developer_guide/index.md

@@ -0,0 +1,124 @@
+# Developer guide
+
+## Running the tests
+
+AiiDA-KKR comes with a set of tests for its functionality. The tests are run through `pytest` and they are defined in `tests/` and the sub directories therein.
+
+The following will discover and run the unit test:
+
+```
+# install aiida-kkr with testing extra
+pip install -e .[testing]
+# go to path where tests are defined
+cd tests
+# create fake executables
+mkdir -p jukkr; cd jukkr && export PATH="$PWD:$PATH"; touch kkr.x; touch voronoi.exe; touch kkrflex.exe; chmod +x kkr.x voronoi.exe kkrflex.exe
+# run tests (-h shows help)
+./run_all.sh -h
+```
+
+The coverage of the tests is controlled via environment variables (see `-h` option of `run_all.sh`), e.g.:
+
+```
+RUN_VORONOI=1 RUN_KKRHOST=1 ./run_all.sh
+```
+
+If you use aiida-core >= v2.0 you should first migrate the input data:
+
+```
+python migrate_exports.py
+```
+
+In order to recreate test export files you need real executables instead of the fakes we create above:
+
+```
+cd tests
+# this will download the code and compile voronoi, kkrhost and kkrimp
+./jukkr_installation.sh -f
+# make sure the executables are found in the PATH
+cd jukkr && export PATH="$PWD:$PATH" && cd ..
+```
+
+If your changes require updates to reference data (checked via the `pytest-regressions` package) you should add the `--force-regen` option to the pytest run:
+
+```
+pytest --force-regen workflows/test_bs_wc.py
+```
+
+## Automatic coding style checks
+
+Enable enable automatic checks of code sanity and coding style:
+
+```
+pip install -e .[pre-commit]
+pre-commit install
+```
+
+After this, the [yapf](https://github.com/google/yapf) formatter,
+the [pylint](https://www.pylint.org/) linter
+and the [pylint](https://www.pylint.org/) code analyzer will
+run at every commit.
+
+To run the pre-commit hooks without making a commit use:
+
+```
+pre-commit run --all-files
+```
+
+If you ever need to skip these pre-commit hooks, just use:
+
+```
+git commit -n
+```
+
+## Continuous integration
+
+`aiida-kkr` comes with a `.github` folder that contains continuous integration tests on every commit using [GitHub Actions](https://github.com/features/actions). It will:
+
+1. run all tests for the `django` ORM
+2. build the documentation
+3. check coding style and version number (not required to pass by default)
+
+## Building the documentation
+
+> 1. Install the `docs` extra:
+>
+>    ```
+>    pip install -e .[docs]
+>    ```
+>
+> 2. Edit the individual documentation pages:
+>
+>    ```
+>    docs/source/index.rst
+>    docs/source/developer_guide/index.rst
+>    docs/source/user_guide/index.rst
+>    ...
+>    ```
+>
+> 3. Use [Sphinx] to generate the html documentation:
+>
+>    ```
+>    cd docs
+>    make html
+>    ```
+
+Check the result by opening `build/html/index.html` in your browser.
+
+## PyPI release
+
+With every tag that is pushed a continuous deployment github action runs that uploads the code to pypi.
+Note that this will only be done if the tests (see Continuous integration) pass.
+
+The latest release is therefore able to be installed via:
+
+```
+pip install aiida-kkr
+```
+
+:::{note}
+When updating the plugin package to a new version, remember to update the version number both in `setup.json` and `aiida_kkr/__init__.py`.
+:::
+
+[readthedocs]: https://readthedocs.org/
+[sphinx]: https://www.sphinx-doc.org/en/master/

docs/source/index.md

@@ -0,0 +1,84 @@
+# [AiiDA] plugin for the [Jülich KKRcode]
+
+```{image} images/juKKR_logo_square_new.jpg
+:width: 20%
+```
+
+```{image} images/AiiDA_transparent_logo.png
+:width: 40%
+```
+
+## Welcome to documentation of the AiiDA plugin for the [Jülich KKRcode]!
+
+The plugin is available at <https://github.com/JuDFTteam/aiida-kkr>
+
+If you use this plugin for your research, please cite the following work:
+
+```{eval-rst}
+.. highlights:: Philipp Rüßmann, Fabian Bertoldo, and Stefan Blügel,
+  *The AiiDA-KKR plugin and its application to high-throughput impurity embedding into a topological insulator*.
+  npj Comput Mater **7**, 13 (2021); `DOI 10.1038/s41524-020-00482-5`_
+
+```
+
+Also please cite the [AiiDA] papers:
+
+```{eval-rst}
+.. highlights:: Sebastiaan P. Huber, Spyros Zoupanos, Martin Uhrin, Leopold Talirz, Leonid Kahle, Rico Häuselmann,
+  Dominik Gresch, Tiziano Müller, Aliaksandr V. Yakutovich, Casper W. Andersen, Francisco F. Ramirez, Carl S. Adorf,
+  Fernando Gargiulo, Snehal Kumbhar, Elsa Passaro, Conrad Johnston, Andrius Merkys, Andrea Cepellotti, Nicolas Mounet,
+  Nicola Marzari, Boris Kozinsky, and Giovanni Pizzi,
+  *AiiDA 1.0, a scalable computational infrastructure for automated reproducible workflows and data provenance*,
+  Scientific Data **7**, 300 (2020); `DOI: 10.1038/s41597-020-00638-4`_
+```
+
+and
+
+```{eval-rst}
+.. highlights:: Martin Uhrin, Sebastiaan. P. Huber, Jusong Yu, Nicola Marzari, and Giovanni Pizzi,
+  *Workflows in AiiDA: Engineering a high-throughput, event-based engine for robust and modular computational workflows*,
+  Computational Materials Science **187**, 110086 (2021); `DOI: 10.1016/j.commatsci.2020.110086`_
+```
+
+or if you are using AiiDA\<1.0:
+
+```{eval-rst}
+.. highlights:: Giovanni Pizzi, Andrea Cepellotti, Riccardo Sabatini, Nicola Marzari, and Boris Kozinsky,
+  *AiiDA: automated interactive infrastructure and database for computational science*,
+  Comp. Mat. Sci **111**, 218-230 (2016); `DOI: 10.1016/j.commatsci.2015.09.013`_
+
+```
+
+### Requirements
+
+- Installation of [aiida-core]
+- Installation of KKR codes (*kkrhost*, *kkrimp*, *voronoi*) of the [JuKKR package]
+- Installation of [aiida-kkr]
+
+Once all requirements are installed you need to [set up the computers and codes] before you can submit KKR calcutions using the *aiida-kkr* plugin.
+
+```{toctree}
+:maxdepth: 2
+
+user_guide/index
+developer_guide/index
+API documentation <module_guide/index>
+```
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`
+
+[aiida]: http://www.aiida.net
+[aiida-core]: https://aiida-core.readthedocs.io/en/stable/installation/index.html
+[aiida-kkr]: https://github.com/JuDFTteam/aiida-kkr/blob/master/README.md
+[doi 10.1038/s41524-020-00482-5]: https://doi.org/10.1038/s41524-020-00482-5
+[doi: 10.1016/j.commatsci.2015.09.013]: https://doi.org/10.1016/j.commatsci.2015.09.013
+[doi: 10.1016/j.commatsci.2020.110086]: https://doi.org/10.1016/j.commatsci.2020.110086
+[doi: 10.1038/s41597-020-00638-4]: https://doi.org/10.1038/s41597-020-00638-4
+[judft]: http://www.judft.de/pm/index.php
+[jukkr package]: https://iffgit.fz-juelich.de/kkr/jukkr
+[jülich kkrcode]: http://jukkr.fz-juelich.de
+[set up the computers and codes]: https://aiida-core.readthedocs.io/en/stable/get_started/index.html#setup-of-computers-and-codes

docs/source/module_guide/calculations.md

@@ -0,0 +1,46 @@
+# Calculations
+
+## Voronoi
+
+```{eval-rst}
+.. automodule:: aiida_kkr.calculations.voro
+   :members:
+   :private-members:
+   :special-members:
+```
+
+## KKRcode
+
+```{eval-rst}
+.. automodule:: aiida_kkr.calculations.kkr
+   :members:
+   :private-members:
+   :special-members:
+```
+
+## KKRcode - calculation importer
+
+```{eval-rst}
+.. automodule:: aiida_kkr.calculations.kkrimporter
+   :members:
+   :private-members:
+   :special-members:
+```
+
+## KKRimp
+
+```{eval-rst}
+.. automodule:: aiida_kkr.calculations.kkrimp
+   :members:
+   :private-members:
+   :special-members:
+```
+
+## KKRnano
+
+```{eval-rst}
+.. automodule:: aiida_kkr.calculations.kkrnano
+   :members:
+   :private-members:
+   :special-members:
+```

docs/source/module_guide/data.md

@@ -0,0 +1,5 @@
+# Data
+
+## Multiply data plugin
+
+% Add here any other module you might have

docs/source/module_guide/index.md

@@ -0,0 +1,10 @@
+# Modules provided with aiida-kkr (API reference)
+
+```{toctree}
+:maxdepth: 3
+
+calculations
+workflows
+parsers
+tools
+```

docs/source/module_guide/parsers.md

@@ -0,0 +1,52 @@
+# Calculation parsers
+
+```{toctree}
+:maxdepth: 2
+```
+
+This section describes the different parsers classes for calculations.
+
+## Voronoi Parser
+
+```{eval-rst}
+.. automodule:: aiida_kkr.parsers.voro
+   :members:
+   :private-members:
+   :special-members:
+```
+
+## KKRcode Parser
+
+```{eval-rst}
+.. automodule:: aiida_kkr.parsers.kkr
+   :members:
+   :private-members:
+   :special-members:
+```
+
+## KKRcode - calculation importer Parser
+
+```{eval-rst}
+.. automodule:: aiida_kkr.parsers.kkrimporter
+   :members:
+   :private-members:
+   :special-members:
+```
+
+## KKRimp Parser
+
+```{eval-rst}
+.. automodule:: aiida_kkr.parsers.kkrimp
+   :members:
+   :private-members:
+   :special-members:
+```
+
+## KKRnano Parser
+
+```{eval-rst}
+.. automodule:: aiida_kkr.parsers.kkrnano
+   :members:
+   :private-members:
+   :special-members:
+```

docs/source/module_guide/tools.md

@@ -0,0 +1,34 @@
+# Tools
+
+```{toctree}
+:maxdepth: 2
+```
+
+Here the tools provided by `aiida_kkr` are described.
+
+## Common (work)functions that need aiida
+
+```{eval-rst}
+.. automodule:: aiida_kkr.tools.common_workfunctions
+   :members:
+   :private-members:
+   :special-members:
+```
+
+## KKRimp tools
+
+```{eval-rst}
+.. automodule:: aiida_kkr.tools.tools_kkrimp
+   :members:
+   :private-members:
+   :special-members:
+```
+
+## Plotting tools
+
+```{eval-rst}
+.. automodule:: aiida_kkr.tools.plot_kkr
+   :members:
+   :private-members:
+   :special-members:
+```