结合内联部分管理 Sphinx toctrees

Question

我正在尝试了解如何管理与其他内容位于同一文件中的 toctree 元素。

假设我有一个 thingamajig.rst 章节，如下所示：

Thingamajigs
============

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

Overview
++++++++

Thingamajigs are fun

当我渲染它时 --- foo/bar/baz 有自己的 .rst 文件 --- 它看起来像这样：

但是如果我将 Overview 部分移动到 目录树之前 ，那么它会将目录树向下推到概述部分：

Thingamajigs
============

Overview
++++++++

Thingamajigs are fun

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

有什么方法可以让我的 toctree 位于概述部分之后，但位于 Thingamajigs 部分下方？

或者，我可以这样做吗？

Thingamajigs
============

.. toctree::
   :maxdepth: 2

   Overview          <-- refers to Overview section in same file
   foo
   bar
   baz

Overview
++++++++

Thingamajigs are fun

Answer 1

章节标题层次结构很简单 the order as encountered。因此，您的 ==== 下划线设置标题（“H1”），++++ 下划线设置副标题（“H2”）仅此页面。取决于您所追求的布局...

一个。也许您想要一个“Table of contents”部分作为“Overview”部分的兄弟部分（都在“Thingamajigs”parent 内），因此插入一个新的 H2 部分标题：

Thingamajigs
============

Overview
++++++++

Thingamajigs are fun


Table of contents
+++++++++++++++++

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz

乙。或者，也许您根本不想在章节标题层次结构中显示“概述”，因此可以通过不同的方式突出显示它：

Thingamajigs
============

.. admonition:: Overview

    Thingamajigs are fun

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz

摄氏度。或在此页面内列出标题层次结构，与外部页面分开：

.. contents:: In this page
    :local:

.. beware, that contents directive must appear before any heading hierarchy

Thingamajigs
============

.. toctree::
    :maxdepth: 2
    :caption: In other pages
    
    foo
    bar
    baz

D.或者完全按照您上一个示例显示的方式进行操作：将“概述”内容移出到单独的 ReST 文档中，并将其名称包含在 toctree 指令 body.

中

Answer 2

其他人对toctree和contents发表了评论，我就不重复了。

您可以使用 raw 指令进行破解。

Thingamajigs
============

.. raw:: html

    <h2><span class="section-number">1.1. </span>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>

.. Overview
.. ++++++++

Thingamajigs are fun

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz

为了获得我在 raw 指令中使用的 HTML，我从“概述”及其下划线开始生成 HTML。接下来，我从生成的 HTML 中复制它并如上所示粘贴，在 raw 指令下缩进。最后我把“Overview”和它的下划线注释掉了。您可以调味生的 HTML 来调味。

但是，就我个人而言，我不认为有一个标题，紧接着是“概述”或“简介”标题，紧接着是概述或简介的内容。我会删除标题并简单地显示所需的内容。很明显是什么，那为什么还要标题呢？

Answer 3

可以满足问题中给出的确切规范，但并非没有需要解决方法的重大问题。

Is there any way to have my toctree after the Overview section, but located under the Thingamajigs section?

通过在 Overview 部分中放置一个 toctree，您将该目录树的所有“条目”（.rst 文件）放置在该部分中，因此在部分层次结构中低于该级别。

However, a document must be consistent in its use of section titles: once a hierarchy of title styles is established, sections must use that hierarchy.

将 toctree 置于其假装部分之外将影响 1)“导航”、2)“编号”和 3)“深度”。

解决方法的第一步：

你可以用:hidden:选项在你想要的地方声明一个toctree - 在Thingamajigs部分 - 因此有1), 2)和 3) 按预期工作。 Sphinx 将处理第一个 toctree 声明中的条目，因此之后在 Overview 内声明的 toctree 不会影响 1)、2) 和 3)，因为 .rst 条目已经被处理。

结果：

对应thingamajigs.rst：

Thingamajigs
============

.. toctree::
    :hidden:

    foo
    bar
    baz

Overview
++++++++

Thingamajigs are fun

.. toctree::

    foo
    bar
    baz

以上完全按照问题中指定的方式解决了问题。

（Sphinx 会发出警告，因为同一个 .rst 文件包含在多个 toctree 中，但它们不仅仅是警告。）

解决方法的第二步：

不过，惊喜来了！如果你向上一层，到包含以 thingamajigs.rst 作为条目的 toctree 的 .rst，你会发现 :hidden: toctree 没有呈现，而是可见的 toctree呈现“到位”（乱序）：

结果：

对应level_2_toctree.rst：

***************
Level_2_toctree
***************

.. toctree::

    fill_tree1
    fill_tree2
    fill_tree3
    fill_tree4
    thingamajigs

虽然 1)、2) 和 3) 正在工作（就保留其功能的 toctrees 而言），这给我们留下了一个问题：修复父 toctrees 中的渲染顺序。显而易见的解决方案是在项目符号列表中“按原样”重复原始的较低级别目录树，并添加针对这些部分的引用：

结果：

对应level_2_toctree.rst：

***************
Level_2_toctree
***************

.. toctree::

    fill_tree1
    fill_tree2
    fill_tree3
    fill_tree4

.. toctree::
    :hidden:

    thingamajigs


- :ref:`5.5. Thingamajigs <target_thingamajigs>`


    .. toctree::

        foo
        bar
        baz

    - :ref:`5.5.4. Item Overview <target>`


.. toctree::

    foo2
    bar2

请注意，您必须将 hyperlink targets 添加到原始 thingamajigs.rst。

.. _target_thingamajigs:

Thingamajigs
============

.. toctree::
    :hidden:

    foo
    bar
    baz

.. _target:

Overview
++++++++

Thingamajigs are fun

.. toctree::

    foo
    bar
    baz

解决方法的第三步：

但这还有另一个问题，HTML 主题可能有不同的 CSS 项目符号列表和目录树样式，两者都被处理为不同的 HTML 元素（检查来源）。

一个解决方案是 wrap the block including the 2 delimiting references in a reST directive（一个容器），它允许自定义样式以使块“融入”剩余的 toctree。但是，您必须在提升 toctree 链的每个步骤中传播此自定义。这确实提供了一个通用的解决方案，作为 “概念证明” 将 “portable toctree” 置于上下文之外。两个主要缺点是必须手动重构超链接编号，以及自定义 CSS.

所需的开销和专业知识。

没有更多解决方法：

考虑 Sphinx toctree directive and the reStructuredText contents directive 非常不同。 toctree 的全部意义在于将 .rst 文件链接在一起，而 contents 指令的目的是提供 .rst 文件内容的良好 table它所在的（或部分）。

尝试 contents 指令的有用 :backlinks: 选项，方法是在其文档的 upper index and the corresponding section 之间来回单击。

“理想情况下”避免变通办法的最佳方法是为手头的工作使用正确的工具。

作为上述两个补充的第三个选项是使用由 hyperlink targets 组成的项目符号列表。它很灵活，允许混合包含项目符号列表的 .rst 文件的内部和外部链接。此外，它不会干扰 toctree 或 contents 指令的自动操作 - 这取决于部分。解决方法的第二步包括项目符号列表的两个基本元素。

I'm trying to learn how I can manage a toctree element that is located in the same file as other content.

查看官方 Python 文档中的 toctrees one example, or another example you see the "Flat, Simple, Special cases..." from the Zen of Python reflected. Most prominent documentations I've seen chose simple toctree layouts。

在不更改指定表示的情况下，最有效的解决方案是在 Overview 中使用指向超链接目标的项目符号列表而不是 toctree。

结合内联部分管理 Sphinx toctrees

Managing Sphinx toctrees combined with inline sections

python-sphinx

restructuredtext

toctree