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;

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.

Answer 2

The "rubric" directive may achieve what you want:

http://sphinx-doc.org/markup/para.html#directive-rubric

It doesn't generate section titles in quite the same way, but at least they don't show up in the TOC

Answer 3

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

.. toctree::
    :maxdepth: 2