使文档的标题级别自动依赖于它们所属的 (sub(sub(...))) 文件夹的深度级别

Question

假设我有：

一个 foo0.rst 文件位于我的 sphinx-doc 源文件夹的根目录 (source)，
foo1.rst 文件位于 source、

subfolder1

foo2.rst 文件位于 subfolder1、

subfolder2

即：

$ tree source
source
├── foo0.rst
└── subfolder1
    ├── foo1.rst
    └── subfolder2
        └── foo2.rst

内容相同：

This a title
============

现在，如果 index.rst 包含：

Welcome to Test's documentation!
================================

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   foo0
   subfolder1/foo1
   subfolder1/subfolder2/foo2

make html 给出：

Welcome to Test’s documentation!

Contents:

    • This a title
    • This a title
    • This a title

也就是说所有的标题都是节。

我想得到的是以下内容：

Welcome to Test’s documentation!

Contents:

    • This a title
      ◦ This a title
        ▪ This a title

这是标题：

foo0.rst为一节，
subfolder1/foo1.rst 是小节（而不是节），
subfolder1/subfolder2/foo2.rst 是一个小节（而不是一节）。

因此我的问题是：是否可以将标题级别设置为属于（sub（sub（...）））文件夹的文档自动依赖于它们所属文件夹的深度级别？

Answer 1

应用到 toctree entries is dependent on the theme you are using. The theme's CSS will apply a style to the entries that Sphinx translated into <ul> and <li> depending both on their place within the "document hierarchy" given how you chain the toctrees and how your section structure 的样式在单个 .rst 文件中被组织。

例如，检查 Sphinx 生成的 HTML 个元素。 toctree 将是一个 div class="toctree-wrapper compound"，每个级别的部分被命名为 <li class="toctree-l1">，然后是 <li class="toctree-l2">，等等...

实现您想要的效果的一种方法是使用 .. class:: 指令（如 show here) and apply a ）包围给定的 toctree。但这会影响任何其他 .rst 个文件，您希望将其作为条目包含在 toctree.

中

无论如何，如果重构您的项目，您将承担额外的工作并可能失去自动化。

还有one possible workaround, using the :hidden: option together with the :include: directive. If you declare a hidden toctree before a visible toctree the "document hierarchy" can fix the position of an entry for you in the hierarchy. Afterwards the visible toctree without the :hidden: option will render .rst file entries as a <li> element having a fixed position in the hierarchy. (A thorough example can be seen ).

可以做到，但是会违背toctree的特点。

普遍的解决方案是根据您希望 toctree 的显示方式编写 .rst 文件和部分。（这种方法具有所有优点，唯一的缺点是限制了 .rst 文件的编写方式）。这可能是更好的解决方案，而不是尝试调整 CSS 样式或使用变通方法。

编辑：

我之前写的是对的，但可能太笼统了。因此，我将为该示例提供一种可能的解决方案。如果您想要以下内容：

Contents:

    • This a title (foo0)
      ◦ This a title (foo1)
        ▪ This a title (foo2)

一个简单的选项是使用 toctree 链。如果您不想看到 toctree 文档层次结构中较低的文档，可以将其隐藏。

index.rst

.. toctree::
   :maxdepth: 3

   foo0

并在 foo0.rst

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/foo1

并在 subfolder1/foo1.rst

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/subfolder2/foo2

结果将如您指定的那样。

使文档的标题级别自动依赖于它们所属的 (sub(sub(...))) 文件夹的深度级别

Make the heading levels of documents automatically dependent of the depth's levels of the (sub(sub(...)))folders they belong to

python-sphinx

restructuredtext

sections

toctree