Sphinx: Add templating support to sphinx-apidoc

[goerz]

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__, apidoc creates 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.

[hanshoi]

For me this seems like a feature well worth implementing. Keep up the good job.

[tk0miya]

+1; it would be nice if somebody sends us PR!

[goerz]

Great, I'll work this into a pull request as soon as I have some time

[EricG-Personal]

I would love to see this implemented as well.

[goerz]

I will get back to this at some point, eventually..

[goerz]

Well, basic templating was added in v2.2, and I've decided to finish the job with #6768.

It's a further iteration on better-apidoc, in that it only keeps the central get_members function. However, this will allow to do anything that better-apidoc can currently do