Sphinx - what is different between toctree and content?
<p>I can create table of contents in two ways:</p>

<pre><code>.. contents::
   :local:
   depth: 1
</code></pre>

<p>or as </p>

<pre><code>.. toctree::
    :maxdepth: 1

    index
</code></pre>

<p>What is difference? Where I should use the toctree and where the contents?</p>

<p><a href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents" rel="nofollow"><code>.. contents</code></a> is a doctutils directive (the underlying library which defines ReST and associated utilities) and <strong><em>automatically</em></strong> generates a table of contents from headlines within the current topic.</p>

<p><a href="http://www.sphinx-doc.org/en/stable/markup/toctree.html" rel="nofollow"><code>.. toctree</code></a> is a Sphinx-defined directive in which you <strong>explicitly list documents</strong> whose TOCs will be listed out.</p>

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

<pre><code>===================
Curing World Hunger
===================

.. contents::
   :depth: 1

Abstract
========

â¦

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

â¦
</code></pre>

<p>You'd use <code>.. toctree</code> within an index document which contains basically nothing else:</p>

<pre><code>=================
Scientific papers
=================

Below is a list of papers published here:

.. toctree::
   :maxdepth: 2

   curing_hunger
   â¦
</code></pre>

<p><code>.. toctree</code> takes a list of documents to process, <code>.. contents</code> does not.</p>

python python-sphinx