狮身人面像 - toctree和内容之间有什么不同？

Question

我可以用两种方式创建目录:

.. contents::
   :local:
   depth: 1

或者作为

.. toctree::
    :maxdepth: 1

    index

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

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但不是.