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?

I think you put that documentation as a doc string in the package's __init__.py file. — martineau
– martineau, Commented Nov 12, 2013 at 12:07
I knew I should have it mentioned. I tried exactly that as well, but those comments appear at the end of the generated html page. — Alex
– Alex, Commented Nov 12, 2013 at 12:36

deMangler · Accepted Answer · 2019-01-19 21:18:56Z

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.

edited Jan 19, 2019 at 21:18

answered Dec 8, 2018 at 13:11

deMangler

4773 silver badges17 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

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

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related