Non-TOC headings within a Restructuredtext page

问题:

I'm writing some documentation using Sphinx.

Is there a way to format headings within a page which do not become part of the TOC? Ideally with some hierarchy that is reflected in formatting?

E.g. I want to do

My page TOC heading
===================

Subheading (not in TOC, and should be formatted e.g. smaller than the heading)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Sub-subheading (not in TOC, and formatted e.g. smaller than the subheading)
###########################################################################

Any other suggestions for how to markup the text so that it has a more structured appearance for the reader are also welcome.

回答1:

You can create custom styles for rubrics that mimic your heading styles.

(1) In your ReST source, define custom styles like this:

.. role:: style1
    :class: class1

.. role:: style2
    :class: class2

Here "style_" is the handle to refer to these in ReST, and "class_" is the CSS class name.

(2) Use the above as inline styles in rubrics:

.. rubric:: :style1:`fake H1`

.. rubric:: :style2:`fake H2`

(3) In whatever CSS file makes sense, define styles for the new classes:

.rubric > .class1 {
    whatever
}

.rubric > .class2 {
    whatever
}

Here the "whatever" could be identical to existing styles for H1, H2 etc. if you wish.

Note: in step (3), you could define the CSS selectors more broadly or narrowly. If the new class names are globally unique, the selector could be as simple as .class1; or if you want to use the style just for top-level rubrics like my example, you could use p.rubric > span.class1 instead.

回答2:

Docutils, the reference implementation of reStructuredText, upon which Sphinx is built allows you to pass options to the table of contents directive which allow you to control how deep you want your table of contents to go into your document hierachy. From the reStructuredText documentation, the contents directive takes a depth option:

depth : integer

The number of section levels that are collected in the table of contents. The default is unlimited depth.

So to get your document structure with only your top level headings included in the table of contents, you could use

.. contents: Table of Contents
   :depth: 1

Edit: It seems that Sphinx implements its own table of contents directive, so you can use

.. toctree: Table of Contents
   :maxdepth: 1

instead of the first code block above. Also, take a look at the hidden option, this might be useful to control further the levels included in the table of contents.

回答3:

For me, I had to add both :maxdepth:1 and :titlesonly: to the toctree section. This is added in the "parent" rst file (or whichever file contains the .. toctree::.