How to create top-level documentation in sphinx automatically from code?

Question

I have a python package and I am able to create sphinx documentation from the python code automatically with

sphinx-apidoc -f -o source --full path_to_package
make html

This works fine, and the html lists all submodules with their documentation.

But in the html I see the following sections/text:

Package name
  Submodules
  First module
    docu...
  Second module
    docu ...

Each module does have its documentation, but how to place tom documentation text directly below the package name? I want to have the following structure:

Package name
  General package documentation...
  Submodules
  First module
    docu...
  Second module
    docu ...

How to generate a documentation to appear on the top-level of a sphinx-generated documentation, describing the whole package, by ONLY change code in the python package? I do not want to change/add/modify any of the files generated by sphinx.

Is this possible, and how to do that?

Answer 1

First put the documentation as a doc string in the packages __init__.py file.

Then look in the docs folder containing your .rst files. Edit the .rst for the package - the one with the Module contents at the end.

Then cut the Module Contents section and paste it to be at the top, above subpackages. Then run make html.

I realise that the op stated only changing python code in the original question, but given his later comment this does seem to be the answer.