More on Toctrees

For your review, the information on the .. toctree:: directive at Sphinx:

The TOC tree page.

Now, here are some tips.

You probably want :hide: not :hidden:

.. toctreee:: will take either of the arguments above, and they do virtually the same thing. Both will cause the toctree to be “hidden”, which is to say, NOT rendered on the page, where normally a .. toctree:: will show up as a list of links in a tree-like form. However, :hidden: causes the items on the .. toctree:: to also not be included in the navigation hierarchy as it appears on the left side of the help file (or on the page derived from the docset’s contents.rst file). :hide:, on the other hand, will allow the unrendered items to be included in the navigation hierarchy.

You can comment your toctree

This isn’t documented anyeffingwhere in Sphinx documentation, which is a major drag.

Do this:

.. toctree::

   Item1
   Item2
      Item3
   Item4

and it has the effect of smoothly toctree-ing Items 1, 2, and 4, and skipping Item3. If you try to use the standard comment markup (..) in a toctree to omit an item, you’ll get an error.

You can itemize your toctree

Toctrees will parse in order of presentation. So if you want, you can go from this:

Here is some text.  Followed by a toctree.

.. toctree::

   item1
   item2
   item3

The first item is about something. The second item is about something else. The third item is about a third thing.

You could do this:

Here is some text about this section.

.. toctree::

   item1

This item describes the first things.

.. toctree::

   item2

This is the second item, that covers things not described in the preceding section.

.. toctree::

   item3

This is the last thing.

In either case, you should get a navigation hierarchy that looks like this:

PARENT
   Item1
   Item2
   Item3

The latter form is a very useful way of both constructing the toctree and providing a narrative description of the contents of a given section, when working on the main (top) page of that section. Note, however, that ICG Helps do not currently require one method or the other as standard practice.