search

aiidateam / aiida-core

The official repository for the AiiDA code
https://aiida-core.readthedocs.io
Other
436 stars 189 forks source link

Sphinx directives are no longer hooked into sphinx.ext.autodoc #3689

Open greschd opened 4 years ago

greschd commented 4 years ago

The AiiDA sphinx extension previously supported just using .. automodule::, by hooking into sphinx.ext.autodoc. This no longer works, as can be seen by this part of the test / demo documentation:

image

It should also be checked if there is a way to turn it off. For example https://github.com/lsmo-epfl/aiida-lsmo/blob/develop/docs/source/apidoc/aiida_lsmo.rst currently uses automodule, and I'm not sure if the intended behavior is the "regular" class documentation or not.

chrisjsewell commented 4 years ago

Despite an initial fix in #4470, this issue remains open because currently the directive is written in such a way that it does not allow for the auto-documented objects to be referenced in the same or a similar way as they now can with :py:class: or :py:meth:. This is because the AiidaProcessDocumenter overwrites their assignment as a class object, but does not similarly store an object on the py domain.

chrisjsewell commented 4 years ago

Basically, I believe it requires a bit of a re-write to achieve this.

greschd commented 4 years ago

It should also be checked if there is a way to turn it off.

This definitely still applies - for example the CalcJob and WorkChain themselves are probably meant to be documented like a "regular" class.

chrisjsewell commented 4 years ago

Oh and also, as mentioned in https://github.com/aiidateam/aiida-core/issues/3300#issuecomment-712499025 the actual docstrings need to be nested parsed