Task 7: Menus and Navigation

Sphinx can automatically build a site navigation menu (called the TOC Tree) and a table of contents on each page. These use different directives.

A StackOverflow user describes the difference between the two TOCs as:

.. contents is a doctutils directive (the underlying library which defines ReST and associated utilities) and automatically generates a table of contents from headlines within the current topic.

.. toctree is a Sphinx-defined directive in which you explicitly list documents whose TOCs will be listed out.

TOC Tree (Site Menu)

RST uses directive ..toctree:: to generate the site navigation tree. Some useful parameters are depth and caption.

The depth parameter determines how many heading levels to show in the TOC. The default value of :maxdepth: 2 includes heading 1 and 2 labels.

Note

You must add files to the TOC Tree manually. Sphinx will generate a warning if a file is not included in the TOC Tree.

  1. First, you include the ..toctree:: directive in a file (usually in an index file for a documentation section)

    • The default index.rst file contains the root TOC file.

    • You can build on that file.

  2. Then, you list the RST files that you want to include in the TOC.

  3. You can include files at the same level or in subdirectories.

    Default index.rst file
    Welcome to Demo's documentation!
================================

.. toctree::
    :maxdepth: 2
    :caption: Contents:

    getting_started
    user_guide/index
    downloads/index
    faq
    contact_us

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

    Hint

    Include an index file in a sub-directory that includes a toctree for that directory.

    In the example above, the user_guide.rst file could contain its own TOC that gets included here.

  4. You can use globbing. See the Sphinx documentation to learn about the topic.

    .. toctree::
    :glob:

    intro*
    recipe/*
    *

Page TOC

Each page can have a TOC using .. contents directive.

The depth parameter determines how many heading levels to show in the TOC. Omit to show all headings in the document.

Sample Usage
**********
Page Title
**********

.. contents:: Table of Contents


Section 1
=========

References