How to structure Sphinx docs for lots of modules

Question

How do I best structure Sphinx docs (for Read the Docs) if I need to both support "regular" prose documentation and API documentation for 30+ modules?

There are a number (<10) of regular prose documentation pages such as "Getting started", "Building the code", "FAQ", "Support", etc. I know how to handle those.

On the other hand my project consists 30+ modules for which the API documentation cannot be extracted from code (non-Python) but must also be written manually. Each module has n functions and each must be documented with the same structure. I'd like to have a .rst per module.

So, the directory structure I'd like to have is as follows:

docs
├── building.rst
├── faq.rst
├── ...
├── index.rst
└── modules
    ├── node.rst
    ├── ...

In the Read the Docs side navigation (i.e. the ToC) I'd like to see this represented as

+ Building (header 1)
 - chapter 1 (header 2)
 - ...
+ FAQ
 - question 1
 - ...
+ Modules
 + node (header 1 from `modules/node.rst`)
   - node.foo()
   - node.bar()
 + ...

Can/should this be achieved somehow by placing another index.rst in the modules directory?

Answer 1

You should create a hierarchy of index files that contain toctree directives that reference files that contain their own toctree directives. Here's a sample layout:

index.rst:

Index
=====

.. toctree::

   modules/index

modules/index.rst:

Modules
=======

.. toctree::

   node1
   node2

modules/node1.rst:

Node 1
======

Node 1 contents

modules/node2.rst:

Node 2
======

Node 2 contents