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

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}"

Answer 3

Hadn't used Sphinx in a while, but it does seem like they've done a good job updating it. In the past, I had to manually specify the classes since I didn't like how autodoc generated the methods/functions. Now it does seem like you can order them:
.. autoclass:: YourClass
:members: __init__, __getitem__
http://www.sphinx-doc.org/en/stable/ext/autodoc.html