Sphinx extensions for workflow documentation.

[greschd]

To allow auto-generating documentation for workchain inputs / outputs, it would be neat to develop a small Sphinx extension (see doc: http://www.sphinx-doc.org/en/stable/extdev/index.html#dev-extensions).

The idea is to have a restructuredText command like

.. aiidaworkchain:: my_plugin.work.MyWorkChain

that looks up the inputs / outputs (and whatever else we want to display) from the spec and creates a nice little documentation.

It probably makes sense to put this in a separate repository / module, like sphinx.ext.aiida.

[greschd]

Note: I'm starting to work on this here: https://github.com/greschd/sphinx-aiida

[greschd]

Ok, I finished a simple implementation of the workchain documentation directive. The command

.. aiida-workchain:: demo_workchain.DemoWorkChain

produces

@giovannipizzi I propose to move this into aiida_core, as aiida_core.sphinxext. Initially I thought it would be better to have a separate repository, but it seems other projects (matplotlib, bokeh, ...) also keep their Sphinx extensions in the main repo. The advantage is that it can be more easily kept in sync with changes in aiida_core. What do you think about this?

[giovannipizzi]

Looks great! Agreed, for me (should be put the extensions into the docs subfolder? Or is should be importable as aiida.xxx?)

[greschd]

Exactly, it should be importable as aiida.sphinxext, so that it can also be used from plugin docs.

[sphuber]

Fixed in PR #1155