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

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.)