Question

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

假设我有一个thingamajig.rst章节，看起来像这样：

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

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

Overview
++++++++

Thingamajigs are fun

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

但是如果我将Overview部分移到toctree之前，则它将toctree向下推到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”）。取决于您要使用的布局...

A。也许您希望将“目录”部分作为“概述”部分的兄弟姐妹（两者都在“ Thingamajigs”父级中），所以插入一个新的H2部分标题：

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

Overview
++++++++

Thingamajigs are fun


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

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz

B。或者，也许您根本不想在部分标题层次结构中使用“概述”，因此可以通过其他方式突出显示它：

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

.. admonition:: Overview

    Thingamajigs are fun

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz

C。或在此页面中列出标题层次结构，与外部页面分开：

.. 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指令正文中。

Answer 2

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

有什么办法可以使我的toctree在“概述”部分之后但位于Thingamajigs部分下面？

通过将toctree放置在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:选项在Thingamajigs部分中的确切位置声明一个toctree，因此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中，但它们不仅是警告而并非错误。）

解决方法的第二步：

但是，现在来一个惊喜！如果您上一层，进入包含以.rst作为条目的toctree的thingamajigs.rst，您会发现:hidden: toctree没有被渲染，而是可见的toctree是呈现为“就地”（乱序）：

结果：

对应的level_2_toctree.rst：

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

.. toctree::

    fill_tree1
    fill_tree2
    fill_tree3
    fill_tree4
    thingamajigs

尽管1），2）和3）正在运行（就保留了toctree的功能而言），但这给我们带来了一个问题：在父toctree中固定渲染顺序。显而易见的解决方案是在项目符号列表中按原样重复原始的较低级toctree，并添加针对这些部分的引用：

结果：

对应的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主题的项目符号列表和toctree可能具有不同的CSS样式，它们都作为不同的HTML元素处理（检查源代码）。

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

没有其他解决方法：

请考虑Sphinx toctree directive和reStructuredText contents directive的不同。虽然toctree的整个要点是将.rst文件链接在一起，但是contents指令的目的是提供.rst文件（或本节）的漂亮目录）在里面。

通过在upper index和文档的相应section之间来回单击，尝试使用:backlinks:指令的有用的contents选项。

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

与上述两个选项互补的第三个选项是使用由bullet list组成的hyperlink targets。它非常灵活，可以混合包含项目符号列表的.rst文件的内部和外部链接。另外，它不会干扰toctree或contents指令的自动性-它们取决于部分。解决方法的第二步包括项目符号列表的两个基本元素。

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

查看官方Python文档one example或another example中的toctree，您会看到"Flat, Simple, Special cases..." from the Zen of Python的体现。我见过的chose simple toctree layouts最著名的文档。

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

Answer 3

其他人评论了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指令下进行了缩进。最后，我注释掉了“概述”及其下划线。您可以对原始HTML进行调味。

但是，就个人而言，我看不到同时具有标题和“概述”或“简介”标题，紧随其后是概述或简介的内容。我将删除标题，仅显示所需的内容。很明显这是什么，那么为什么需要标题呢？

管理Sphinx toctree与内联部分

3 个答案: