reStructuredText and Sphinx Reference

Example based gentle reference of the reStructuredText and Sphinx syntax, directives, roles and common issues. It demonstrates almost all the markup making it also good for testing Sphinx themes. Free and open-source.

contents

The contents directive searches the current document for section and generates local table of contents at the place where used. The directive may appear anywhere but usually is at the top of the document.

Global and local ToC

Is contents what you really looking for? The directive’s main purpose is to print a document’s ToC in the document body, but many Sphinx themes has “on this page” sidebar that shows current document’s ToC automatically.

../_images/local-toc-in-sidebar.png

If you want table of contents of the whole documentation (not the current document), see toctree.

Explicit title

To change a title, pass custom text as a directive argument right after contents:: (note the space after ::).

Section depth

The number of section levels to be printed. The default is unlimited depth (all section levels).

No current document title

By default, the contents directive prints all sections as sublist of document title. You might use :local: flag that will limit table of contents list to sections from current point in the document and bellow. If is contents with this flag used bellow the document title, it will skip it.

#################################
Contents without a document title
#################################

Testing ``contents::`` directive with ``:local:`` flag.

.. contents::
   :local:

**********
Section L2
**********

***************************************************************
Very very very very very very very loooooooooooooong section L2
***************************************************************

Section L3
==========

Very very very very very very very loooooooooooooong section L3
===============================================================

Previous: caution | Next: danger