ReadTheDocs Theme folderstructure using Sphinx

Question

I want to create a digital version of my lecture notes. I installed sphinx and changed the config.py file such that the ReadTheDocs theme is working.

I want to have a similar structure like in the following screenshot (from the Read the Docs Documentation)

My index.rst looks like

.. Lectures documentation master file, created by
   sphinx-quickstart on Tue Jan  9 20:20:10 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

iLectures
======================================

Hello!

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   intro

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

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

How do I have to change the index.rst to have such a similar structure like in the screenshot? It would also be very nice if I could have an equivalent folder structure on my site as in the navigation? How can I refer to a file which is not in the same directory? I really appreciate any help. tried indenting the new contents after the intro but it only led to an error.

Answer 1

The repository of Read the Docs has a docs directory which provides an example of how to render the navigation as you would like. The following is an explanation of what is going on.

The navigation screenshot is generated from two files, yaml-config.rst and index.rst. In the latter you will see that it references yaml-config.rst underneath a toctree directive.

.. toctree::
   :maxdepth: 2
   :caption: User Documentation

   getting_started
   versions
   builds
   features
   support
   faq
   yaml-config
   guides/index
   api
   embed

The index.rst file describes the file structure of the entire set of documentation, and represented in the navigation, to a maxdepth of 2. The yaml-config.rst file gets parsed by Sphinx and renders the navigation nodes under "Read the Docs YAML Config".