After spending some time checking the generated API doc, I found the current presentation hard to follow. My main issue was to visually track what object was presented.
I took inspiration from the griffe documentation and made some tweaks to the generated documentation.
The highlights is that API documentation is now driven by a script, instead of a dumb recursive call to autodoc. Which enables a couple improvements:
Exclude some packages from the documentation, such as the protobuf classes.
Split each module to have their own page.
In addition, I enabled some options in the generator that were turned off by default. For example, attaching object types to the table of content, providing linking anchors, and merging __init__ with the class definition.
Hopefully those changes makes the API reference easier to navigate. I'm sure there are ways to make it even better, but I want to time-box that effort.
After spending some time checking the generated API doc, I found the current presentation hard to follow. My main issue was to visually track what object was presented.
I took inspiration from the griffe documentation and made some tweaks to the generated documentation.
The highlights is that API documentation is now driven by a script, instead of a dumb recursive call to autodoc. Which enables a couple improvements:
In addition, I enabled some options in the generator that were turned off by default. For example, attaching object types to the table of content, providing linking anchors, and merging
__init__with the class definition.Hopefully those changes makes the API reference easier to navigate. I'm sure there are ways to make it even better, but I want to time-box that effort.