Suggestions for an improved Sphinx autodoc extension

[cehbrecht]

Description

In PR #313 an new Sphinx autodoc extension was added by @huard. This extension generates a nicely formatted Sphinx documentation of a PyWPS process.

This extension relies on Sphinx autodoc which needs to import the Python modules to generate the documentation. This can be troublesome on ReadTheDocs where you only have a virtualenv. Non-Python dependencies (netcdf) can not be installed on ReadTheDocs.

Possible solutions:

• Having a rtd.txt requirements file with dependencies for ReadTheDocs only. Other dependencies should not be loaded when rendering the process documentation ... we only need the process definition.
• Hosting the docs on GitHub (or other appropriate places) and rendering it with our own machinery (conda environment).
• Using sphinx-autoapi. sphinx-autoapi parses Python code statically (no imports), generates YAML files with parsed code structure + docs. It uses then jinja templates to generate the API documentation. To get such nicely rendered documentation at least we need to provide our own templates but probably we would also need to extend the code parser.

Other enhancements:

• sphinx-autoapi just needs to be enabled and the complete API docs will be generated. Would be nice to have auto-generated process docs as well (no matter if with autodoc or autoapi). Currently one needs to add the autodoc directive for each process manually ... which is harder to maintain.

Additional Information

We started discussion in the following ticket: https://github.com/bird-house/emu/issues/16

[cehbrecht]

I have "read the docs":

• Not to much help: https://docs.readthedocs.io/en/latest/faq.html#my-project-isn-t-building-with-autodoc
• RTD supports conda (beta), not tried yet: https://docs.readthedocs.io/en/latest/conda.html

[huard]

I have not tested it yet, but in principle it should be possible to use the automodule directive to automatically document all processes within a module.