python - Sphinx - 目录树和内容有什么不同？

Question

我可以通过两种方式创建目录：

.. contents::
   :local:
   depth: 1

或作为

.. toctree::
    :maxdepth: 1

    index

有什么区别？我应该在哪里使用目录树和内容？

Answer 1

.. contents是一个 doctutils 指令（定义 ReST 和相关实用程序的底层库）并自动从当前主题中的标题生成目录。

.. toctree是 Sphinx 定义的指令，您可以在其中明确列出将列出其 TOC 的文档。

例如，您将.. 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不。