6

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.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
gzost
  • 2,375
  • 1
  • 18
  • 25

3 Answers3

6

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.

Chris Johnson
  • 20,650
  • 6
  • 81
  • 80
3

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.

bcb
  • 1,977
  • 2
  • 22
  • 21
Chris
  • 44,602
  • 16
  • 137
  • 156
  • 1
    For now I'm using the depth setting, and with the present document structure, this is not a problem. Structures where there are different depths per branch are not possible, however. A practical example would be an "Introduction" section which I may want to subdivide, but where these divisions are certainly not of the same importance as those of a "Device Administration" section. I'd want the subdivisions of the latter in the TOC, but not those of the former. – gzost Oct 04 '13 at 12:22
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::.

Brian Madden
  • 951
  • 1
  • 8
  • 21