Structuring Sphinx documentation

Question

I have started documenting a Python project using Sphinx. It is the first time I use it - I am used to tools which work with a JavaDoc-like syntax, and I have some doubts.

Since I want the documentation to appear near the code, I make use of the .. automodule::, .. autoclass:: and .. automethod:: directives. So the structure of my documentation is as follows: index.rst contains the TOC and

.. automodule:: my_main_package

and then the top-level __init__.py contains directives like

.. automodule:: some_subpackage

for each subpackage and so on. Finally each module contains directives

.. autoclass:: some_class
    :members:

for each class in the module.

This mostly works, but what I get is a single page documentation, which is a little odd to work with.

How should I organize my documentation in order to obtain a tree of hyperlinked files? That is, the main package should contain its own documentation and links to each of its subpackages and so on, until each module has its own page.

score 11 · Accepted Answer · edited May 23 '17 at 11:51

11

I found this autopackage script from a comment here. It generates the necessary .rst files according to the structure of your packages.

side note: I still feel I am missing something, as I cannot believe that a tool like Sphinx, which is renowned as the most advanced tool for documenting Python, misses the functionality to do basic API documentation. Hence I will leave the question open for a while before accepting my own answer.

edited May 23 '17 at 11:51

Community

1
1

answered Mar 16 '11 at 07:41

Andrea

20,253
23
114
183

7

Just ran across this question myself. I feel like I'm missing something as well. But this is a huge violation of the DRY principle. Why am I duplicating my entire module structure in .rst files? – Trey Stout Jun 14 '11 at 17:40
4

note, that script is now an integral part of Sphinx known as apidoc: http://sphinx-doc.org/man/sphinx-apidoc.html – ecoe Jan 03 '14 at 02:09

score 3 · Answer 2 · answered Feb 27 '12 at 07:39

Even I am not an expert in this, but I think I can answer what you have asked here(about having the organization of the documentation/ rst files).

The key you may be missing here is instead of using the autoclass/automodule/automethod calls in the same top level TOCs rst-file, this top level file should contain links to other rst files containing these calls.

suppose you have all rst files inside doc dir (and subdirs),

Table of contents
=================
The contents of the docs are:

.. toctree::
    :maxdepth: 1

    module_1/index
    module_2/index

in the dir containing this top level index.rst, you will have subdirs with name module_1 and module_2. These will have index.rst (name is just example specific) which in turn will contain the .. automodule::, .. autoclass::, and .. automethod::. It can contain something like

:mod:`module_1`
---------------

..automodule:: module_1
    :show-inheritance:

.. autoclass:: module_1.MyClass

Of course, this is not something like standard, or ideal way of doing, I am suggesting this because it's neater. you can alternatively have all the rst files with module/class/method docs in the same dir as the top level index.rst, with structure

Table of contents
=================
The contents of the docs are:

.. toctree::
    :maxdepth: 1

    module_1
    module_2

and the same dir will contain the doc-files module_1.rst, module_2.rst etc. The paths are relative to the config.py file.

Thank you for your answer, but if understand well this means replicating the module structure in a bunch of rst files, which is far from ideal. The point of my question is how to let Sphynx find this on its own, which is the task of the script I have linked. — Andrea, Feb 27 '12 at 09:17
@Andrea Well I think, replicating structure isn't necessary, its just my taste, python docutils and rst allows us to make any structure, we just need to include links. Maybe I didn't understand your question properly, but with whatever I have understood, maybe you shouldn't include `.. automodule::` in your index.rst. — 0xc0de, Feb 28 '12 at 07:17
Well, the question is the following. I have a python package including API documentation in Sphynx format. I want to be able to extract this documentation, but I do not want to have to manually create a rst file for each python file - I think this should be the task of Sphynx itself. How can I do this? In my answer, for instance, I link a script that does this task. If I understand correctly your answer, you suggest to do this manually — Andrea, Feb 28 '12 at 09:25

score 0 · Answer 3 · answered Mar 15 '11 at 23:26

0

I am by no means an expert on Sphinx, but from reading the documentation it seems that you can include TOC trees in subdirectories. The TOC tree page also gives some information on paths within the tree; have you experimented with using paths in the tree?

answered Mar 15 '11 at 23:26

asthasr

9,125
1
29
43

1

I am not an expert either, so I may be missing something really basic. But if I understand this correctly, in order to use the TOC I should create a bunch of .rst files. So I have to duplicate the structure. Instead I'm not creating additional .rst files: all the documentation is in the Python source. Please correct me if I misunderstood your reply. – Andrea Mar 15 '11 at 23:33

Structuring Sphinx documentation

3 Answers3

Linked