Document private classes which are inherited by public classes
- Dominant language
- Python
- Stars
- 7
- Forks
- 10
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 5
Description
# 📚 Documentation Request
Enabling the nit-picky mode in the sphinx build has revealed some cases where a public class inherits from a private class. This results in the following warnings:
```
lib/ants/fileformats/namelist/umgrid.py:docstring of ants.fileformats.namelist.umgrid.CAPGridRegular:1: WARNING: py:class reference target not found: ants.fileformats.namelist.umgrid._CAPGrid
lib/ants/fileformats/namelist/umgrid.py:docstring of ants.fileformats.namelist.umgrid.CAPGridVariable:1: WARNING: py:class reference target not found: ants.fileformats.namelist.umgrid._CAPGrid
lib/ants/regrid/interpolation.py:docstring of ants.regrid.interpolation.Conservative:1: WARNING: py:class reference target not found: ants.regrid.interpolation._StratifyScheme
lib/ants/regrid/interpolation.py:docstring of ants.regrid.interpolation.Linear:1: WARNING: py:class reference target not found: ants.regrid.interpolation._StratifyPointsScheme
lib/ants/regrid/interpolation.py:docstring of ants.regrid.interpolation.Nearest:1: WARNING: py:class reference target not found: ants.regrid.interpolation._StratifyPointsScheme
```
We could either make these private classes public, or include `:meta public:` in the docstring, since according to the [sphinx documentation](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html):
> autodoc considers a member public if its docstring contains :meta public: in its Info field lists, even if it starts with an underscore.
(see "Options and advanced usage")
We will need to remove these from the `nitpick_ignore` option in [conf.py](https://github.com/MetOffice/ANTS/blob/0a4c714dc9be06d6da6669fd01ef1eec7a6f96c2/docs/source/conf.py#L120).
Contributor guide
Research direction
Start with lib/ants/fileformats/namelist/umgrid.py and lib/ants/regrid/interpolation.py, where the affected private classes are documented through public subclasses. Read docs/source/conf.py and the Sphinx autodoc documentation, then choose the documented-public approach described in the issue. Done means the affected references no longer produce nit-picky warnings and the corresponding entries are removed from nitpick_ignore.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100