Hide Sphinx subsections from main TOCTree

13
votes

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;

5
python-sphinxsectionstoctree
Maybe the titlesonly option is what you are looking for. See sphinx-doc.org/markup/toctree.html. – mzjn
I tried it but it does exactly the opposite of what I want, keeping the titles and hiding the childrens TOCTrees. – Bruno Augusto
possible duplicate of Non-TOC headings within a Restructuredtext page – Chris

5 Answers

11
votes

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.

7
votes

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

4
votes

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

.. toctree::
    :maxdepth: 2
2
votes

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>
0
votes

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>