geopython / geopython/pywps

Suggestions for an improved Sphinx autodoc extension

Open
#343 2 comments 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
Python
Stars
186
Forks
117
Avg merge
11d 20h
Merged PRs (30d)
1

Description

# 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](http://sphinx-autoapi.readthedocs.org/). 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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.