Question

我在获取目录（TOC）时遇到问题，以显示我的文档首页的子部分。

我的首页上有很多部分，我希望这些部分能够显示在TOC中。子部分的显示适用于TOC中包含的每个其他页面，但不适用于自己。

我的index.rst代码：

=====
Title
=====

Subsection
----------

Some documentation.

Contents
--------

.. toctree::
   :maxdepth: 2

   self
   development

我期望在TOC中看到的是：

标题
- 第
- 内容
开发
- 第

相反，我得到的是：

标题
开发
- 第

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

Answer 1

问题中的版式布局存在几个问题：

相反，我得到的是：

标题

发展

小节

使用self作为toctree条目会使包含的.rst文件的outermost section title被包含在toctree条目的该行中。 self条目将不呈现子节或兄弟节，而仅显示最外面的节标题。这违反了toctree条目的常规属性。

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

title和development被错误地呈现为节层次结构中的同一级别。当.rst文件包含在toctree中时，其各节将放置在声明了toctree指令所在节的节层次结构中的下面。

title

.rst将被重复两次，因为它们的级别不同。

相应的标题。rst：

=====
Title
=====

Subsection
----------

Some documentation.

Contents
--------

.. toctree::
   :maxdepth: 2

   self
   development

相应的development.rst：

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

some text

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

对应的external.rst：

Exterior
========

.. toctree::
    :maxdepth: 4

    title

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

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

标题

小节

内容

发展

小节

最简单的选择是使用单独的文件title.rst和development.rst，将它们放在index.rst顶部的同一级别。

对应的index.rst：

Exterior
========

.. toctree::

    title
    development

要获得给定.rst文件内部和外部的引用树，最好的解决方案是使用bullet list中的简单hyperlink targets。

相应的标题。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>`

相应的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::指令只会改变toctree问题的位置，而不能完全解决它们。

Answer 2

您可以直接使用reStructuredText中的TOC指令：

.. contents::

请参阅http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents

在目录中添加self的子部分

2 个答案: