Python sphinx 结合内联截面管理Sphinx树

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

目录树
元素

假设我有一个类似于以下内容的thingamajig.rst章节：

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

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

Overview
++++++++

Thingamajigs are fun

当我渲染它时--foo/bar/baz有自己的.rst文件--

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

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

Overview
++++++++

Thingamajigs are fun


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

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

Overview
++++++++

Thingamajigs are fun

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz


有没有办法将我的目录树放在概览部分之后，但放在Thingamajigs部分下？

或者，我可以这样做吗

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

.. toctree::
   :maxdepth: 2

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

Overview
++++++++

Thingamajigs are fun

Thingamajigs
============
.. 目录树：：
：maxdepth:2
概述章节标题层次结构简单明了。因此，您的====下划线设置标题（“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文档中，并将其名称包含在
目录树
指令正文中。
节标题层次结构非常简单。因此，您的====下划线设置标题（“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文档中，并将其名称包含在
目录树
指令体中。
其他人对
目录树
和
内容
发表了评论，因此我不会重复它们

您可以使用
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

Thingamajigs
============
.. 原始：：html
1.1. 概述
.. 概述
.. ++++++++
事情很有趣
.. 目录树：：
：maxdepth:2
福
酒吧
巴兹

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

然而，就我个人而言，我不认为在标题后面紧跟着“概述”或“简介”标题，然后紧跟着概述或简介的内容有什么意义。我会删除标题，只显示所需的内容。很明显它是什么，为什么它需要一个标题呢？
其他人对
目录树和
内容发表了评论，所以我不会重复它们

您可以使用
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

Thingamajigs
============
.. 原始：：html
1.1. 概述
.. 概述
.. ++++++++
事情很有趣
.. 目录树：：
：maxdepth:2
福
酒吧
巴兹

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

然而，就我个人而言，我不认为在标题后面紧跟着“概述”或“简介”标题，然后紧跟着概述或简介的内容有什么意义。我会删除标题，只显示所需的内容。很明显它是什么，那么为什么它需要一个标题呢？
可以满足问题中给出的确切规范，但并非没有需要解决的重大问题

有没有办法把我的目录树放在概览部分之后，但放在Thingamajigs部分下面

通过将目录树放置在
概述
节中，您将把目录树的所有“条目”（
.rst
文件）放置在该节中，从而在该节层次结构的该级别之下


将一棵树调整到其假装的部分之外将影响1“导航”，2“编号”和3“深度”

解决方法的第一步：

您可以使用
：hidden:
选项在
Thingamajigs
部分中准确地声明目录树，从而使1）、2）和3）按预期工作。Sphinx将处理第一个目录树声明中的条目，因此之后在
概述
中声明的目录树将不会影响1）、2）和3），因为
.rst
条目已被处理

结果是：


相应的
thingamajigs.rst
：

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

.. toctree::
    :hidden:

    foo
    bar
    baz

Overview
++++++++

Thingamajigs are fun

.. toctree::

    foo
    bar
    baz

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

.. toctree::

    fill_tree1
    fill_tree2
    fill_tree3
    fill_tree4
    thingamajigs

***************
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

上述问题完全符合问题中的规定

（Sphinx将发出警告，因为同一个
.rst
文件包含在多个目录树中，但它们不是错误，只是警告。）

解决方案的第二步：

然而，现在来了一个惊喜！如果您向上移动一级，到包含目录树的
.rst
，目录树的条目为
thingamajigs.rst
，您会发现
：hidden:
目录树w