Documenting plugin packages

If you used the AiiDA plugin cutter, your plugin package already comes with a basic documentation that just needs to be adjusted to your needs.

  1. Install the docs extra:

    pip install -e .[docs]
  2. Populate, delete, or add to the individual documentation pages:

  3. Use Sphinx to generate the html documentation:

    cd docs

    Check the result by opening build/html/index.html in your browser.

  4. Host your documentation online on ReadTheDocs. Simply sign up and import your project. Make sure to add the path to the requirements file docs/requirements_for_rtd.txt and the Python configuration file docs/source/ in Admin => Advanced settings.

Note: When updating the plugin package to a new version, remember to update the version number both in setup.json and aiida_mycode/

Sphinx extension

AiiDA defines a Sphinx extension to simplify documenting some of its features. To use this extension, you need to add aiida.sphinxext to the extensions list in your Sphinx file.

WorkChain directive

The following directive can be used to auto-document AiiDA workchains:

.. aiida-workchain:: MyWorkChain
    :module: my_plugin

The argument MyWorkChain is the name of the workchain, and :module: is the module from which it can be imported. By default, the inputs which are not stored in the database are also shown. This can be disabled by passing the :hide-unstored-inputs: flag.

The aiida-workchain directive is also hooked into sphinx.ext.autodoc, so if you use the corresponding directives (automodule, autoclass), it will automatically use the aiida-workchain command for WorkChain classes.