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?

Roseleeroselia

Similar question: https://mcmap.net/q/470110/-customize-templates-for-sphinx-apidoc/407651. – Joselow

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!

Insociable

to me this accomplished nothing near what the OP wanted. you just changed the TOC, but the internal docs are the same because the generated .rst have those titles by default – Tartrazine

I'm directing sphinx-apidoc to not create the headings by default with the -E option. With this option enabled, if your module has a proper docstring header, Sphinx will use that instead of generating one. – Insociable

Indeed, I didn't notice the difference because the packages didn't have docstrings, so the headings were still there, but even modules without docstrings had no headers in the .rst files. – Tartrazine

Did you figure out a way to remove Subpackage and Submodule as well? Then using the name og subpackages and submodules instead. – Anson

@JenGarcia ... if your module has a proper docstring header. How do you set that? Couldn't find anything about it anywhere. – Anson

Once you get into more complex structures, the fix involves text replacement like @Jakob suggested in their answer. – Insociable

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

Undercoating

I have the same problem as @Roseleeroselia , and I have tried :maxdepth: 2 and :titlesonly: in my index.rst toctree, and I still get those headings. The problem is that sphinx-apidoc puts these headings into the generated .rst files. Any idea on how to work around them? Like @ocoe says, one can always edit them away from the .rst, but then you lose the whole point of letting sphinx-apidoc generate these files for you, as you would have to edit/post-process them each time :( – Bratislava

Answer 3

The answer by Jen Garcia helped a lot but it requires to put repeat package names in docstrings. I used a Perl one-liner to remove the "module" or "package" suffix in my Makefile:

docs:
    rm -rf docs/api docs/_build
    sphinx-apidoc -MeT -o docs/api wdmapper
    for f in docs/api/*.rst; do\
        perl -pi -e 's/(module|package)$$// if $$. == 1' $$f ;\
    done
    $(MAKE) -C docs html

Pepita

Do you have a similar fix for make.bat ? – Anson

@Anson sorry I don't develop under Windows. The perl code could be replaced by a little python script that does the same, but I am happy with the current solution under Unix. – Pepita

I get a syntax error when using the perl script: syntax error at -e line 1, near ". ==" Execution of -e aborted due to compilation errors. – Gunboat

@Gunboat what OS and Perl version do you use? Looks like you missed a $ (?) – Pepita

Answer 4

I didn't want to use the titles within my docstrings as I was following numpy style guidelines. So I first generate the rst files and then run the following python script as a post-processing step.

from pathlib import Path


src_dir = Path("source/api")
for file in src_dir.iterdir():
    print("Processed RST file:", file)
    with open(file, "r") as f:
        lines = f.read()

    junk_strs = ["Submodules\n----------", "Subpackages\n-----------"]

    for junk in junk_strs:
        lines = lines.replace(junk, "")

    lines = lines.replace(" module\n=", "\n")

    with open(file, "w") as f:
        f.write(lines)

This script is kept in the same directory as the makefile. I also add the following lines to the makefile.

html:
    # rm -r "$(BUILDDIR)"
    python rst_process.py
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Now running make html builds the documentation in the way I want.

Cabrilla

Answer 5

I'm not sure I'm 100% answering your question, but I had a similar experience and I realized I was running sphinx-apidoc with the -f flag each time, which created the .rst files fresh each time.

Now I'm allowing sphinx-apidoc to generate the .rst files once, but not overwriting them, so I can modify them to change titles/etc. and then run make html to propagate the changes. If I want to freshly generate .rst files I can just remove the files I want to regenerate or pass the -f flag in.

So you do have to change the rst files but only once.

Roseline

Answer 6

In newer versions of Apidoc, you can use a custom Jinja template to control the generated output.

The default templates are here: https://github.com/sphinx-doc/sphinx/tree/5.x/sphinx/templates/apidoc

You can make a local copy of each template using the same names (e.g. source/_templates/toc.rst_t) and invoke sphinx-apidoc with the --templatedir option (e.g. sphinx-apidoc --templatedir source/_templates).

Once you are using your own template file, you can customize it however you want. For example, you can remove the ugly "package" and "module" suffix, which is added at this stage.

Aviator