在 toctree 中添加 self 的子部分

Question

我在获取目录 (TOC) 以显示文档首页的小节时遇到问题。

我的首页上有许多部分，我希望这些部分显示在 TOC 中。小节的显示适用于 TOC 中包含的所有其他页面，但不适用于 self.

我的index.rst代码：

=====
Title
=====

Subsection
----------

Some documentation.

Contents
--------

.. toctree::
   :maxdepth: 2

   self
   development

我希望在 TOC 中看到的是：

• 标题
  • 小节
  • 内容
• 发展
  • 小节

相反，我得到的是：

• 标题
• 发展
  • 小节

到目前为止，我找到了一种解决方案，但并不令人满意。我可以将所有内容放在一个单独的页面中，然后将内容包含在index.rstusing.. include:指令中，并将单独的页面放在 TOC 中。这使 TOC 看起来正确，但会创建一个重复的页面，该页面现在包含在导航中（上一页/下一页）。

Answer 1

问题中的部分布局存在几个问题：

相反，我得到的是这样的：

• 标题
• 发展
  • 小节

用作self目录树条目使得包含文件的最外层节标题.rst包含在目录树条目的该行中。该self条目不会呈现子部分或同级部分，仅呈现最外面的部分标题。这违背了 toctree 条目的通常属性。

在问题的示例中可以立即注意到上述结果的两个后果：

• title并被development错误地呈现为位于部分层次结构中的同一级别。当.rst文件包含在 toctree 中时，其节将放置在节层次结构中声明 toctree 指令的节的下方。

• title.rst如果包含放置在外部八叉树中，则将重复两次，因为在不同的级别上。

对应标题.rst：

=====
Title
=====

Subsection
----------

Some documentation.

Contents
--------

.. toctree::
   :maxdepth: 2

   self
   development

对应的开发.rst：

development
===========

some text

Subsection inside development.rst
---------------------------------

对应的external.rst：

Exterior
========

.. toctree::
    :maxdepth: 4

    title

针对与 toctree 指令的属性相反的节结构并不是一个好的设计选择。根据问题中的规范，最简单且概念上最合理的解决方案是使用指令contents列出给定.rst文档中的部分。

我希望在目录中看到的是：

• 标题
  • 小节
  • 内容
• 发展
  • 小节

最简单的选择是使用单独的文件title.rst并将development.rst它们放在index.rst目录树的同一级别中。

对应的index.rst：

Exterior
========

.. toctree::

    title
    development

要实现给定文件的内部和外部引用树，.rst最好的解决方案是使用超链接目标的简单项目符号列表。

对应标题.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
---------------------------------

对应的external.rst：

Exterior
========

.. toctree::
    :maxdepth: 4

    title
    development

然后使用 .. include: 指令将内容包含在 index.rst 中

使用该.. include::指令只会改变目录树问题的位置，而不会完全解决它们。