ImperialCollegeLondon / ImperialCollegeLondon/virtual_ecosystem
Can't get `sphinx.autodoc` to work sensibly for registries
- Dominant language
- Python
- Stars
- 20
- Forks
- 5
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 34
Description
**Is your feature request related to a problem? Please describe.**
We have added various registries containing objects that are needed to get each model to run, e.g. the `CONSTANTS_REGISTRY` which contains the constants classes for each model. Part of the motivation for making these registries is ease of documentation.
However, I can't get the `sphinx` extension `autodoc` to generate sensible output when trying to document the registry. `automodule`, `autoclass` and `autodata` all document the registry but don't document the classes contained within it.
**Describe the solution you'd like**
We either need to work out how to get `sphinx.autodoc` to play nicely with registries, or find an alternative way of automatically documenting the contents of the relevant registries.
**Describe alternatives you've considered**
I tried to write a custom `sphinx` directive to handle this automatic documentation, but hit a bit of a brick wall. I think this was mainly my lack of familiarity with `docutils` (which `sphinx` is based on) though.
Contributor guide
Research direction
Start by reproducing the documentation issue around CONSTANTS_REGISTRY using Sphinx autodoc's automodule, autoclass, and autodata directives. Read the registry definitions and the relevant Sphinx/docutils directive documentation; the work is complete when the classes contained in relevant registries are automatically documented in sensible output.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100