Customize templates for `sphinx-apidoc`

Question

I've recently tried using sphinx-apidoc from Sphinx to help generate Sphinx specific reStructuredText from the API of a Python project.

However, the result I'm getting is:

Anyone know if I can customize the template sphinx-api uses for its output? Specifically, I'd like to:

• Get rid of all the "Submodules", "Subpackages" and "Module contents" headings, and
• Have the results from docstring in my __init__.py files appear directly under the packages, so that if I click a package name, the first thing I see is the package documentation. At the moment, this documentation is placed under the slightly weird "Module contents" heading at the very end of each package section.

The "Submodules" and "Subpackages" headings are redundant I think, since the normal headings for packages/modules is "xxx.yyy package" and "xxx.yyy.zzz module".

The structure I would like for the above small example is

• orexplore.components package
  • orexplore.components.mbg120 module
• orexplore.simulators package
  • orexplore.simulators.test package
    • orexplore.simulators.test.mbg120 module
  • orexplore.simulators.mbg120 module

Where clicking the packages, the first thing I'd see on the page would be the package documentation.

Or maybe even just

• orexplore.components
  • orexplore.components.mbg120
• orexplore.simulators
  • orexplore.simulators.test
    • orexplore.simulators.test.mbg120
• orexplore.simulators.mbg120

if there was some way to visually distinguish packages/modules (color? emblem?) instead of the quite wordy " package" and " module".

Answer 1

I implemented better-apidoc, a patched version of the sphinx-apidoc script that adds full support for templates.

It adds a -t/--template option, allowing to pass a template directory that must contain template files package.rst and module.rst. See package.rst and module.rst for an example. These render to e.g. http://qnet.readthedocs.io/en/latest/API/qnet.algebra.operator_algebra.html.

Answer 2

The sphinx-apidoc script uses the apidoc.py module. I am not able to provide detailed instructions, but in order to remove headings or otherwise customize the output, you'll have to write your own version of this module. There is no other "template".

Note that if the API and module structure is stable, there is no need to run sphinx-apidoc repeatedly. You can post-process the generated rst files to your liking once and then place them under version control. See also https://stackoverflow.com/a/28481785/407651.

Update

From Sphinx 2.2.0, sphinx-apidoc supports templates. See https://stackoverflow.com/a/57520238/407651.