MetOffice / MetOffice/ANTS

Document private classes which are inherited by public classes

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.