Hide Sphinx subsections from main TOCTree

Question

Is it possible to hide one (or all) subsections present in a RST file from the main TOCTree?

Let me describe a little more:

index.rst

:doc:`Label <path/to/rst/file>`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. toctree::

   Label <path/to/rst/file>
   Label <path/to/rst/file>

   Label of Children TOCTree <path/to/rst/children/file>

children/file.rst

Children Title
==============

.. toctree::

   Label of Grandchildren 1
   Label of Grandchildren 2


Subsection 1
------------

Subsection 2
------------

Subsection 3
------------

These files, after built, will result, in main TOCTree:

• Label
• Label
• Label of Children
  • Label of Grandchildren 1
  • Label of Grandchildren 2
  • Subsection 1
  • Subsection 2
  • Subsection 3

And I would like to hide the Subsections, keeping only the TOCTrees, as many and as deep as I want. E.g:

• Label
• Label
• Label of Children
  • Label of Grandchildren 1
  • Label of Grandchildren 2

But, if the hyperlink associated to Label of Children is clicked, the Subsections are listed as usual;

Bonded

Maybe the titlesonly option is what you are looking for. See sphinx-doc.org/markup/toctree.html. – Aquila

I tried it but it does exactly the opposite of what I want, keeping the titles and hiding the childrens TOCTrees. – Bonded

possible duplicate of Non-TOC headings within a Restructuredtext page – Numerate

Answer 1

This took me awhile to figure out, but I think I finally got it. The "trick" is that you need to set directives in both the parent rst which contains the toc and the child rst which contains the section.

For me, I added :maxdepth:1 and :titlesonly: to the toc in the parent rst, and then :titlesonly: to the toc in the child, and that works perfectly. That allows me to have hierarchical subsection formatting in the child which is rendered properly that does not show up in the TOC.

Levy

Just what I needed. I actually specifically want :maxdepth: 2 in my index.rst toctree, but even still :titlesonly: worked just fine for suppressing the subsections I've defined in the child pages. – Invade

Answer 2

The rubric directive may achieve what you want.

.. rubric:: title

This directive creates a paragraph heading that is not used to create a table of contents node.

Corpuscle

Answer 3

You can use the maxdepth parameter of toctree to set how deep the TOC is:

.. toctree::
    :maxdepth: 2

Furthermost

Answer 4

Try changing ------------------ to ***************** for Subsection 1 etc. Also, you can make multiple toctrees each with their own maxdepth, eg

.. toctree::
    :maxdepth: 2

    Label <path/to/rst/file>
    Label <path/to/rst/file>

.. toctree::
    :maxdepth: 1
    Label of Children TOCTree <path/to/rst/children/file>

Labrecque

Answer 5

You can make your own tags

Where you want your header type

|start-h3| My Title |end-h3|

At the end of the file write

.. |start-h3| raw:: html

     <h3>

.. |end-h3| raw:: html

     </h3>

Stlaurent