我在获取目录 (TOC) 以显示我的文档首页的小节时遇到问题。
我的首页上有许多部分，我希望这些部分显示在目录中。小节的显示适用于目录中包含的所有其他页面，但不是 self.
我的index.rst代码：
=====
Title
=====
Subsection
----------
Some documentation.
Contents
--------
.. toctree::
:maxdepth: 2
self
development
我希望在 TOC 中看到的是：
相反，我得到的是：
到目前为止，我找到了一种解决方案，但它并不令人满意。我可以将所有内容放在单独的页面中，然后将内容包含在index.rstusing.. include:指令中，并将单独的页面放在 TOC 中。这使 TOC 看起来正确，但会创建一个重复的页面，该页面现在包含在导航中（上一页/下一页）。
您可以直接使用来自 reStructuredText 的 TOC 指令：
.. contents::
请参阅http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents
问题中的部分布局存在几个问题：
相反，我得到的是：
- 标题
- 发展
- 小节
用作self目录树条目会使包含文件的最外层部分标题.rst包含在目录树条目的该行中。该self条目不会呈现子节或兄弟节，只会呈现最外层的节标题。这违背了目录树条目的通常属性。
在问题的示例中可以立即注意到上述两个结果：
title并且development被错误地呈现为在节层次结构中的同一级别。当一个.rst文件包含在一个 toctree 中时，它的节被放置在节层次结构中声明 toctree 指令的节的下方。
title.rst如果包含放置在外部目录树中，将重复两次，因为在不同的级别。
对应title.rst：
=====
Title
=====
Subsection
----------
Some documentation.
Contents
--------
.. toctree::
:maxdepth: 2
self
development
对应的开发.rst：
development
===========
some text
Subsection inside development.rst
---------------------------------
对应的exterior.rst：
Exterior
========
.. toctree::
:maxdepth: 4
title
以与 toctree 指令的属性相抵触的节结构为目标并不是一个好的设计选择。根据问题中的规范，最简单且概念上最合理的解决方案是使用contents指令列出给定.rst文档中的部分。
我希望在 TOC 中看到的是：
- 标题
- 小节
- 内容
- 发展
- 小节
最简单的选择是使用单独的文件title.rst并将development.rst它们放在目录树中的同一级别index.rst。
对应的index.rst：
Exterior
========
.. toctree::
title
development
要实现给定文件的内部和外部引用树，.rst最好的解决方案是使用一个简单的超链接目标项目符号列表。
对应title.rst：
.. _target_title:
=====
Title
=====
.. _target_subsection_title:
Subsection inside title.rst
---------------------------
Some documentation.
.. _target_contents:
Contents
--------
text
- :ref:`Title <target_title>`
- :ref:`Subsection <target_subsection_title>`
- :ref:`Contents <target_contents>`
- :ref:`Development <target_development>`
- :ref:`Subsection <target_subsection_development>`
对应的开发.rst：
.. _target_development:
development
===========
some text
.. _target_subsection_development:
Subsection inside development.rst
---------------------------------
对应的exterior.rst：
Exterior
========
.. toctree::
:maxdepth: 4
title
development
然后使用 ..include: 指令将内容包含在 index.rst 中
使用该.. include::指令只会改变 toctree 问题的位置，而不能完全解决它们。