matousc matousc - 2 months ago 12
Python Question

Sphinx - what is different between toctree and content?

I can create table of contents in two ways:

.. contents::
:local:
depth: 1


or as

.. toctree::
:maxdepth: 1

index


What is difference? Where I should use the toctree and where the contents?

Answer

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

You'd use .. contents for example within a document to generate an overview of contents within the page, e.g.:

===================
Curing World Hunger
===================

.. contents::
   :depth: 1

Abstract
========

…

Problem description
===================

…

You'd use .. toctree within an index document which contains basically nothing else:

=================
Scientific papers
=================

Below is a list of papers published here:

.. toctree::
   :maxdepth: 2

   curing_hunger
   …

.. toctree takes a list of documents to process, .. contents does not.