How to create a title that will not appear in the toctree with Sphinx?

I am using Sphinx to create documentation for a Python module.

I wold like to add subtitles on a page but I don't want them to appear in the toctree.

I want small sections and short (few lines) descriptions. Adding every section title to the toctree would make browsing the docs much harder.

Here is my index.rst:

Welcome to ModernGL's documentation!
====================================

.. figure:: Examples/images/02_uniforms_and_attributes.png
    :scale: 50 %
    :alt: ModernGL
    :align: center
    :figclass: align-center

Start `here <ModernGL.html>`_.

.. toctree::
    :maxdepth: 4
    :caption: Contents:

    ModernGL <ModernGL.rst>
    Examples <Examples.rst>
    Contributing <Contributing.rst>


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

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

I want to add some subtitles:

Subtitle 1
**********

Subtitle 2
**********

Subtitle 3
**********

Subtitle 4
**********

I checked the documentation and I have no clue what type of underline should I use. Not sure if there is a special underline that will be convert the title to a <h4> or <h5>

With a github README.md adding more # characters will result in smaller titles. What is the equivalent in *.rst?

The build documentation can be found here and it does not contain subtitles since it would ruin the current structure of the docs.

Solution

Did you try to add hidden in your toctree directive? Something like:

.. toctree::
    :maxdepth: 4
    :hidden:
    :caption: Contents:

    ModernGL <ModernGL.rst>
    Examples <Examples.rst>
    Contributing <Contributing.rst>

This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive – this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.

As for "section headers" (titles and subtitles) this extract from official Sphinx documentation might give you an answer:

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings.

You might try to use ^ character for your subsections to render out the heading you need.