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.

Answer 1

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.