Add templating support to sphinx-apidoc #3545
Description
The sphinx-apidoc utility has some shortcomings, including
- For modules with a lot of members, there is no overview of the members. The resulting page is very hard to navigate.
- If modules expose imported objects through
__all__,apidoccreates stubs for both the exporting module and the module where the object was originally defined. This leads to duplicate references. It is generally hard to control which module members will show up in the documentation - Apidoc produces potentially unwanted headings "Submodules", "Subpackages" and "Module contents". There is no option besides post-processing to disable these.
These and other concerns could be addressed by adding templating to the sphinx-apidoc utility. I've started to explore this option by forking the apidoc script to a tentative better-apidoc. It's a fairly small patch (I made sure to have the diff to the original apidoc.py as small as possible) that adds a-t/--templates option to the script. If this option is present, Jinja-templates module.rst and package.rst are used to render the output. See the better-apidoc README for which variables are exposed to the template and example templates. Currently, this is designed (and may further evolve) to meet my needs to document the QNET project.
I would welcome any comments and suggestions on this, especially regarding to which template variables would be useful. If there is a consensus that having template support would be useful, I would be happy to eventually prepare a pull-request to merge better-apidoc back into Sphinx (after some period of gestation).
I'm aware that sphinx-autosummary already has support for templating, so there is some overlap here. However, as far as I can tell, autosummary will generate individual files for all module members. It doesn't seem to cover the use case of having one file per module or package combining both useful summaries and the full documentation of each member.