Improve layout of per-class documentation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 6
- Forks
- 3
- PR merge metrics
- No merged PRs in 30d
Description
Tech Debt
From https://github.com/ni/nitypes-python/pull/151#discussion_r2214412199:
Currently, we generate one class per page and the bintime and waveform classes have detailed documentation in the class docstring. This is almost what I want, except:
- The constructor signature(s) is at the top, followed by the detailed documentation, then the rest of the class members.
- The parameters for the constructor are not documented like other methods.
Some ideas on how to improve the layout:
- Go back to one module per page and split nitypes.waveform into submodules (nitypes.waveform.analog, etc.). Note that this breaks compatibility unless we continue to alias the classes into nitypes.waveform, in which case we would need to use the autoapi-skip-member callback to control which copy of the class is documented.
- Set
autoapi_add_toctree_entry=Falseand create separate.rstfiles that use.. autoapimodule::,.. autoapiclass::, etc. I think this will give us control of the page before/after the class documentation. - Create a custom autoapi template.
- Switch to autodoc.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by examining the generated per-class documentation for the bintime and waveform classes, especially nitypes.waveform and its proposed submodules. Review the listed AutoAPI approaches, including autoapimodule:: and autoapiclass::, and determine which layout gives control over class and constructor content. Done means constructor signatures and parameter documentation appear in the intended order without breaking the public aliases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100