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

Question

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.

Answer 1

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.

Answer 2

Timestamp: this answer's sphinx-doc.org excerpts are from May, 2021.

Short answer:

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

You're looking for the .. toctree:: directive's :titlesonly: option.

Documentation for .. toctree::'s :titlesonly: here:

• https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents
• Under Directives > Table of contents > .. toctree:: > Additional options > titlesonly option
• Definition -- Quoted Text (from that link)

  If you want only the titles of documents in the tree to show up, not other headings of the same level, you can use the titlesonly option:

  .. toctree::
    :titlesonly:
    foo
    bar
  

Details:

I'm assuming that you do want all of the .rst entries in your example's .. toctree:: directive to appear in the TOC (table of contents) which Sphinx inserts there, but that you do not want any Section Headers within these .rst files to appear in that TOC.

Documentation for Section Headers here:

• https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
• Definition -- Quoted text from that link:

  Section headers (ref) are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:

  =================
  This is a heading
  =================
  

  ...

  • # with overline, for parts
  • * with overline, for chapters
  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • ", for paragraphs

By default, without the :titlesonly: option under the .. toctree:: directive, the rendered TOC tree will display both the "titles" of the listed .rst files and also any Section Headers listed within these .rst files.

Using the :titlesonly: option under the .. toctree:: directive, these "Headings" a.k.a. Section Headers will not be rendered in the TOC tree (and only the "titles" of the .rst files will be displayed).

---

Example without :titlesonly: option:

• If your .. toctree:: looks like this (without the :titlesonly: option):
   
  
  
• Then the TOC is rendered
  listing both the .rst page titles
  and also their Section Headers:
   

---

Example with :titlesonly: option present:

• If your .. toctree:: looks like this (with the :titlesonly: option):
   
  
  
• Then the TOC is rendered
  listing only the .rst page titles
  but not their contained Section Headers:
   

---

Related, but different scope:

This answer (above) is for the .. toctree:: directive.

Different steps are required for altering the sidebar, and these steps can be different depending on the custom theme you're using with Sphinx.

If you also want to modify the TOC displayed by the sidebar, here are some related links to help you get started:

• https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars
• https://www.sphinx-doc.org/en/master/faq.html?highlight=sidebar#how-do-i
• https://www.sphinx-doc.org/en/master/usage/theming.html?highlight=sidebar
• so/q/14477396 : How to expand all the subsections on the sidebar toctree in Sphinx?
• so/q/18969093 : How to include the toctree in the sidebar of each page

(I'd list more details for this, but I'm still investigating. I'm currently looking for a way to (1) display Section Headers in the Sidebar TOC using the sphinx_rtd_theme, but to (2) not display Section Headers in the .. toctree:: inserts.)