Sections

ICG Usage Notes

Prefer .. rubric:: to underlined section headings for putting headings in documents.

In most cases, we do not use reST section headings below the doc title, we use .. rubric:: directives. More below.

Section headings do get used in places, but there are no tried-and-true guidelines for this: it is done mostly as a matter of judgment. For now, just assume section headings should be avoided.

Rubrics vs. Section Titles

Rubrics do not show up on the navigation tree, section titles do. Therefore, if you want to make a second, third, or nth-level heading in your document, but do not want that heading to show up on the tree, you’ll need to use a rubric.

Rubrics vs. Section Titles

The markup that produced the above looks like this:

.. _rubs_v_secs:

Rubrics vs. Section Titles
++++++++++++++++++++++++++

Rubrics do not show up on the navigation tree, section titles do.
Therefore, if you *want* to make a second, third, or nth-level heading in
your document, but *do not* want that heading to show up on the tree, you'll
need to use a rubric.

.. rubric:: Rubrics vs. Section Titles
   :class: h2
   :name: rubs_v_secs2

The markup that produced the above looks like this::

As you can see, visually the section and the rubric produce the same thing. The styling of rubrics is handled by the :class: option; values “h2”, “h3”, and “h4” will yield 2nd, 3rd, and 4th level headings, respectively.

There are no > h4 styles. The perceived need for them should be correctly interpreted as a sign that the document you have is poorly formed and should be restructured.

Update For the Experienced Sphinx User

It used to be that you could not make implicit links to .. rubrics:: (an attempt to link to the rubric in the example above, if formed like this, wouldn’t work: :ref:`rubs_v_secs2` (this is an implicit link) and it had to be formed like this: :ref:`link label <rubs_v_secs2>` (this is an explicit link), but this isn’t true anymore. That said, explicit links are still preferred.

Gory Details

The observant will note this very document is using subheadings. “What gives? They don’t show up on the tree? Did you lie?”

In this case they don’t, because all the documents in this internal documentation are not included on the tree, therefore subheadings within them do not appear either. So, the longer, more accurately true statement is: for a document put onto the tree through a .. toctree:: directive that is formed to do so (as they generally are), its subheadings will automatically be added to the tree.

Request

Though valid, please do not use the asterisk (*) character for title/section underlining.