Sphinx API docs are empty
- Dominant language
- Rust
- Stars
- 30.5k
- Forks
- 3.2k
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 66
Description
The `python_sphinx` target for `ninja` builds docs for `aqt` Python bindings only and they're mostly empty.
I'd like to add docstrings to the `pylib` and `aqt` classes and functions for easier-to-read auto-generated API docs generation using existing `autoapi` and `Sphinx` while adding `sphinx.ext.napoleon` and `sphinx.ext.autodoc.typehints` extensions.
The existing single-quote annotations on some functions help when working in the IDE but Sphinx doesn't generate docs from them. Also, not all functions or classes in the python bindings have annotations.
I already started working on this and have a couple functions "doc-stringed" in the `decks.py` file of pylib.
Before I get too far, how would you prefer to break up docstring commits so that edits are manageable to review?
Contributor guide
Research direction
Start with the `python_sphinx` target and the existing `autoapi` and Sphinx configuration, then review the partially docstringed `pylib` `decks.py` file. Check how the proposed `sphinx.ext.napoleon` and `sphinx.ext.autodoc.typehints` extensions affect the `pylib` and `aqt` API output; done means the scope and commit breakdown are agreed and the generated docs are no longer mostly empty.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100