Sphinx apidoc section titles for Python module/package names

Question

When I run sphinx-apidoc and then make html it produces doc pages that have "Subpackages" and "Submodules" sections and "module" and "package" at the end of each module/package name in the table of contents (TOC). How might I prevent these extra titles from being written without editing the Sphinx source?

here's an example doc pages I would like to make (notice TOC):

http://selenium.googlecode.com/svn/trunk/docs/api/py/index.html#documentation

I understand it is due to the apidoc.py file in the sphinx source (line 88):

https://bitbucket.org/birkenfeld/sphinx/src/ef3092d458cc00c4b74dd342ea05ba1059a5da70/sphinx/apidoc.py?at=default

I could manually edit each individual .rst file to delete these titles or just remove those lines of code from the script but then I'd have to compile the Sphinx source code. Is there an automatic way of doing this without manually editing the Sphinx source?

Answer 1

I was struggling with this myself when I found this question... The answers given didn't quite do what I wanted so I vowed to come back when I figured it out. :)

---

In order to remove 'package' and 'module' from the auto-generated headings and have docs that are truly automatic, you need to make changes in several places so bear with me.

First, you need to handle your sphinx-apidoc options. What I use is:

sphinx-apidoc -fMeET ../yourpackage -o api

Assuming you are running this from inside the docs directory, this will source yourpackage for documentation and put the resulting files at docs/api. The options I'm using here will overwrite existing files, put module docs before submodule docs, put documentation for each module on its own page, abstain from creating module/package headings if your docstrings already have them, and it won't create a table of contents file.

That's a lot of options to remember, so I just add this to the end of my Makefile:

buildapi:
    sphinx-apidoc -fMeET ../yourpackage -o api
    @echo "Auto-generation of API documentation finished. " \
          "The generated files are in 'api/'"

With this in place, you can just run make buildapi to build your docs.

Next, create an api.rst file at the root of your docs with the following contents:

API Documentation
=================

Information on specific functions, classes, and methods.

.. toctree::
   :glob:

   api/*

This will create a table of contents with everything in the api folder.

Unfortunately, sphinx-apidoc will still generate a yourpackage.rst file with an ugly 'yourpackage package' heading, so we need one final piece of configuration. In your conf.py file, find the exclude_patterns option and add this file to the list. It should look something like this:

exclude_patterns = ['_build', 'api/yourpackage.rst']

Now your documentation should look exactly like you designed it in the module docstrings, and you never have to worry about your Sphinx docs and your in-code documentation being out of sync!

Answer 2

It's probably late, but the options maxdepth or titlesonly should do the trick.

More details : http://sphinx-doc.org/latest/markup/toctree.html