Question

What is the correct way, if any, of splitting a source document in Sphinx?

I have a large file, let’s call it file1.rst, the structure of which is like this:

Section 1
*********

Subsection 1
============

Subsection 2
============

Subsection 3
============

Each subsection is very long, and the source file has become unmanageable. I would like to put each subsection in a different source file.

I tried with the include directive:

Section 1
*********
.. include:: subsection1.rst
.. include:: subsection2.rst
.. include:: subsection3.rst

But it’s issuing warnings that labels in subsection1.rst are duplicated in section1.rst (not true, the label is only in the sub-document).

Alternatively, is there any possibility to change the hierarchy in the TOC directive?

Answer 1

I’m answering my own question (shame!) because I finally understood what I was getting wrong.

The TOC, table of contents directive can be used multiple times. This will result in the hierarchical structure that I was looking for.

I hope this can be of help for those who, like me, thought that there can be one TOC only.