Menu hierarchy¶

Technically, the file hierarchy on disc must not affect the menu hierarchy in any way. But, as a general convention, we use the common practice that the file hierarchy reflects the menu hierarchy.

Multi-file solution¶

So, the menu structure for the files described under Directories and file names

Documentation/
|
 --> Index.rst
|
 --> Topic1/
       |
       -> Index.rst
       -> Subtopic1.rst
       -> Subtopic2.rst

would look something like this:

Documentation/Index.rst:

.. toctree::
   :hidden:

   Topic1/Index

Documentation/Topic1/Index.rst

.. toctree::
   :hidden:

   Subtopic1
   Subtopic2

See Example Toctree to see how this is rendered.

Single-file solution¶

What you can also do, is put everything into one file, e.g. Index.rst contains:

=======
Chapter
=======

Topic 1
=======

Subtopic 1
----------

some text

Subtopic 2
----------

some text

The rendered result will look the same as the multi-file example above, meaning the menu hierarchy and the rendered headings on the page.

Tip

Whatever variant you choose, it depends what is already common practice in the manual you are working on and what is easiest to manage.