More on Toctrees
For your review, the information on the .. toctree::
directive at Sphinx:
Now, here are some tips.
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.
Was this helpful? ... | PFC 6.0 © 2019, Itasca | Updated: Nov 19, 2021 |