ImperialCollegeLondon / ImperialCollegeLondon/virtual_ecosystem

Can't get `sphinx.autodoc` to work sensibly for registries

Open
#301 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.