We currently use automodapi in our sphinx documentation.
We've discussed removing automodapi since it's not being very actively maintained, so below I describe two options for replacing it with built-in Sphinx functionality.
Advantages of removing automodapi include:
- Reduced maintenance overhead to maintain compatibility with Sphinx updates
- More flexibility in what other plugins we use, e.g.
automodapi uses autodoc internally so we currently couldn't switch to something like autoapi
A general challenge with the options discussed below is that it is somewhat difficult to prototype changes to the documentation. Because of the way that Sphinx and autodoc are, almost any change to the documentation will generate at least some new warnings due to missing references, duplicate exports, missing docstrings, etc.
Since we treat sphinx warnings as errors this means that if I create a PR to demonstrate changes to the documentation, the changes won't show up in the hosted docs unless I resolve all warnings.
Replace with autosummary
automodapi uses Sphinx's built-in autosummary plugin internally, and it's possible to replicate the same generated structure by just using autosummary directly combined with custom templates for the generated pages.
The one thing automodapi provides that isn't provided by Sphinx a simple way to skip/ignore specific items in a module. In order to skip certain items we would have to create a handler for the autodoc-skip-member hook.
Replace with autodoc
This option is pretty straightforward to implement but would result in significantly different formatting for the generated documentation. Specifically:
- No summary tables of class/module items
- All items in a given module would be documented on a single page rather than having separate pages for each
If we're okay with those changes then we can essentially just swap out each .. automodapi:: call with .. automodule::.
Replace Sphinx?
This is obviously not a near-term solution, but if we thought that at some point we would want to move away from Sphinx entirely then we may want to just stick with automodapi for now and look into more extensive changes later on.
We currently use
automodapiin our sphinx documentation.We've discussed removing
automodapisince it's not being very actively maintained, so below I describe two options for replacing it with built-in Sphinx functionality.Advantages of removing
automodapiinclude:automodapiusesautodocinternally so we currently couldn't switch to something likeautoapiA general challenge with the options discussed below is that it is somewhat difficult to prototype changes to the documentation. Because of the way that Sphinx and autodoc are, almost any change to the documentation will generate at least some new warnings due to missing references, duplicate exports, missing docstrings, etc.
Since we treat sphinx warnings as errors this means that if I create a PR to demonstrate changes to the documentation, the changes won't show up in the hosted docs unless I resolve all warnings.
Replace with
autosummaryautomodapiuses Sphinx's built-inautosummaryplugin internally, and it's possible to replicate the same generated structure by just usingautosummarydirectly combined with custom templates for the generated pages.The one thing
automodapiprovides that isn't provided by Sphinx a simple way to skip/ignore specific items in a module. In order to skip certain items we would have to create a handler for theautodoc-skip-memberhook.Replace with
autodocThis option is pretty straightforward to implement but would result in significantly different formatting for the generated documentation. Specifically:
If we're okay with those changes then we can essentially just swap out each
.. automodapi::call with.. automodule::.Replace Sphinx?
This is obviously not a near-term solution, but if we thought that at some point we would want to move away from Sphinx entirely then we may want to just stick with
automodapifor now and look into more extensive changes later on.