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



假设我有:

  • 我的sphinx-doc源文件夹根目录(source)的foo0.rst文件,
  • foo1.rstsubfolder1的子文件夹中的文件source
  • subfolder2的子文件夹中的foo2.rst文件subfolder1

那是:

$ 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(...))) 的文档文件夹自动取决于 它们所属文件夹的深度级别?

应用于toctree条目的样式取决于您使用的主题。主题的 CSS 将对 Sphinx 翻译成<ul><li>的条目应用样式,具体取决于它们在"文档层次结构">中的位置,给定您如何链接toctrees以及如何组织各个.rst文件中的部分结构。

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

实现所需目标的一种方法是使用.. class::指令(如此处所示)包围给定toctree并应用自定义样式。但这会影响您希望作为条目包含在该toctree中的任何其他.rst文件的样式。

在任何情况下,如果您重构项目,您将承担额外的工作并可能松散的自动化。

还有一种可能的解决方法,将:hidden:选项与:include:指令一起使用。如果在可见toctree之前声明隐藏toctree,则"文档层次结构">可以为您确定条目在层次结构中的位置。之后,没有:hidden:选项的可见toctree会将.rst文件条目呈现为在层次结构中具有固定位置的<li>元素。(在这篇文章中可以看到一个详尽的例子)。

这是可以做到的,但您将违背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

结果将按照您指定的方式显示。

最新更新