Can Sphinx emit the 'module contents' first and the 'submodules' last?

Question

I typically put the high-level documentation for a Python package into the docstring of its __init__.py file. This makes sense to me, given that the __init__.py file represents the package's interface with the outside world. (And, really, where else would you put it?)

So, I was really quite surprised when I fired up Sphinx for the first time and saw this content buried near the very end of the package documentation, after the content for all of the submodules.

This seems backward to me. The very first thing the user will see when he visits the page for a package is the documentation of the submodule that just happens to come first alphabetically, and the thing he should see first is right near the bottom.

I wonder if there is a way to fix this, to make the stuff inside of __init__.py come out first, before all of the stuff in the submodules. And if I am just going about this in the wrong way, I want to know that. Thanks!

Answer 1

Updated Answer (thank you, Donal Fellows):

https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html#cmdoption-sphinx-apidoc-M

Original Answer:

Yes, there is an option to do this, it's just not documented here. Inside my copy of Sphinx-1.3.3/sphinx/apidoc.py I found this:

parser.add_option('-M', '--module-first', action='store_true',
                  dest='modulefirst',
                  help='Put module documentation before submodule '
                  'documentation')

I tried it and it works like a charm.

Answer 2

It is also possible to add this option in the conf.py file.

Search in conf.py for the line where the string containing the sphinx-apidoc command is (located in a try section) and add the "--module-first" option.

The new line will look like this:

cmd_line_template = "sphinx-apidoc --module-first -f -o {outputdir} {moduledir}"