假设我有:
- 我的
sphinx-doc
源文件夹根目录(source
)的foo0.rst
文件, foo1.rst
subfolder1
的子文件夹中的文件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
结果将按照您指定的方式显示。