Search code examples
pythonpython-sphinxrestructuredtext

How can i add links to other pages in reStructuredText?


I'm using Sphinx to create a documentation for my project, but i'm struggling to understand basic concepts about RST.

So i have a basic project with an index.rst and i'm using the sphinx-rtd-theme to style it. So i created the html and on the left i have a menu, just like here. Now i created a new page for the documentation, and the rst file is called auth.rst.

What i don't understand is how do i add links to other pages such as auth.rst in the side menu on the left? Right now, i have on that menu two links: Welcome to Test-API's documentation! and Indices and tables, how do i add new links to other pages of my documentation? I don't understand where is this defined in the code below and i didn't find much about this

Welcome to Test-API's documentation!
================================

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



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

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

Solution

  • Underneath the ':caption ...' you write the relative path (from where this RST file is on disk) to the target rst (auth.rst in your case)

    Example, given this folder structure:

    RST
      |- a.rst
      |- b.rst
      |-folder2 
        |-c.rst
        |-d.rst
    

    In a, if I wanted to reference b and c, I could have:

    .. toctree::
       :maxdepth: 2
       :caption: Contents:
       b
       folder2/c
    

    And if I wanted to reference d from c, I would do this in c:

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