ni / ni/nitypes-python

Improve layout of per-class documentation

Open
#155 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
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:

Image

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:

  1. The constructor signature(s) is at the top, followed by the detailed documentation, then the rest of the class members.
  2. 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=False and create separate .rst files 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.

AB#3202297

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.