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).

Sample section#

To show how#

contents directive#

works with 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.

:orphan:

#################################
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
===============================================================