Items and sub-items in different directories and listed in menu - Sphinx

Question

I'm creating a project using the Sphinx tool.

And to keep the organization, I separated the sub-items into directories with the name of the item "Mother", as follows:

├──conf.py
├──index.rst
├──Item_1.rst
├──Item_2.rst
├──Item_3.rst
└──Directory_Item_2/
    └── Subitem_2.1.rst

But when building the documentation with make html I get the following errors:

/source/index.rst:10: WARNING: toctree contains reference to nonexisting document '   Item_2/Subitem_2.1

Note that in this first error, sphinx is interpreting the tab indentation as a space belonging to the name Item_2/Subitem_2.1

And just below:

source/Item_2/Subitem 2.1.rst: WARNING: document isn't included in any toctree

My index.rst file looks like this

.. teste documentation master file, created by
   sphinx-quickstart on Tue Jun 27 14:39:35 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to teste's documentation!
=================================

.. toctree::
   :maxdepth: 3

   Item 1
   Item 2
      Item 2/Subitem 2.1
   Item 3



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

I tried to remove Item_2/Subitem_2.1 from the index.rst file but without success.

This has prevented the read_the_docs_theme side menu from forming correctly.

The way I found for the correct formation of the menu, was to put all the content of all the sub-items, directly inside the Item_2.rst, making a file with more than 12000 lines.

Knowing that this is still the beginning, I would like to organize each sub-item, within a directory, with the name of the item "Mother", and within that directory, the sub-items. But when doing this, the menu with the contents does not find these sub-items.

As a summary, I need Sphinx to understand that items in a separate directory are part of the "Mother" item

I apologize if something is not clear, I'm still not very used to the forum tools.

I thank you all!

I need Sphinx to understand that items in a separate directory are part of the "Mother" item, and for it to be correctly constructed in the left menu of read_the_docs

Answer 1

Don't indent your toctree entries. Use the actual file names, with or without file extensions, and their relative paths from index.rst.

.. toctree::
   :maxdepth: 3

    Item_1
    Item_2
    Directory_Item_2/Subitem_2.1
    Item_3