Sections

Some Section Titles are Underlined

Request

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

Second level headings generally use “+” for underlining, but any underlining character can be used as long as consistency is maintained.

Some Section Titles are Rubrics

What’s going on here? Simple: an underlined section is made a part of the navigation tree, a c rubric directive is not.

.. _icgsphinx-sections:

Sections
#########

Some Section Titles are Underlined
++++++++++++++++++++++++++++++++++

.. admonition:: Request
   :class: aside

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

Second level headings generally use "+" for |ullink|_, but any underlining
character can be used as long as consistency is maintained.

.. rubric:: Some Section Titles are Rubrics
   :class: h2
   :name: example-rubric

What's going on here? Simple: an underlined section is made a part of the
navigation tree, a |c| |rubriclink|_ directive is not.

ICG Usage Notes

Prefer .. rubric:: to underlined section headings for putting sections in documents.
Use h2, h3, and h4 with the :class: option to obtain second-, third-, and fourth-level headings (note there is an h1 but it is rarely needed, as doc titles are “h1” and for those underlining with “#” is used).
Include a :name: option with a unique anchor name so that links can be built to the section denoted by this rubric.
Regarding underlining: this is valid and subsections that use it are found throughout ICG documents. However, there are no tried-and-true guidelines for this: it is done mostly as a matter of judgment. For now, just assume underlined subsection headings should be avoided in favor of rubrics.
Tip: note that content following a rubric directive is not aligned with its :name: and :class: option labels; this is correct markup.

Getting Nitpicky

Examining the source for this document would show that it is using underlined 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 underlined subheadings within them do not appear either.