ankitects / ankitects/anki

Sphinx API docs are empty

Open
#3,974 2 comments 0 reactions 0 assignees View on GitHub
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.