Sphinx - what is different between toctree and content?

Question

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 1

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