Sphinx - toctree 和内容之间有什么不同？

Question

我可以通过两种方式创建 table 内容：

.. contents::
   :local:
   depth: 1

或

.. toctree::
    :maxdepth: 1

    index

有什么区别？我应该在哪里使用 toctree 以及内容在哪里？

Answer 1

.. contents 是一个 doctutils 指令（定义 ReST 和相关实用程序的底层库）并且 自动 生成一个 table 个来自当前主题标题的内容。

.. toctree 是一个 Sphinx-defined 指令，您可以在其中 明确列出文档 ，其目录将被列出。

例如，您可以在文档中使用 .. contents 来生成页面内容的概览，例如：

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

.. contents::
   :depth: 1

Abstract
========

…

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

…

您将在一个基本上不包含任何其他内容的索引文档中使用 .. toctree:

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

Below is a list of papers published here:

.. toctree::
   :maxdepth: 2

   curing_hunger
   …

.. toctree 接受要处理的文档列表，.. contents 不接受。