reStructuredText 页面中的非 TOC 标题

Question

我正在使用 Sphinx 编写一些文档。

有没有一种方法可以格式化页面中不属于 TOC 的标题？ 最好有一些反映在格式中的层次结构？

例如我想做

My page TOC heading
===================

Subheading (not in TOC, and should be formatted e.g. smaller than the heading)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Sub-subheading (not in TOC, and formatted e.g. smaller than the subheading)
###########################################################################

也欢迎任何其他关于如何标记文本以使其对读者具有更结构化外观的建议。

Answer 1

对我来说，我必须将 :maxdepth:1 和 :titlesonly: 添加到目录树部分。这被添加到“父”第一个文件（或任何包含.. toctree:: 的文件中。

Answer 2

您可以为模仿您的标题样式的量规创建自定义样式。

(1) 在您的 ReST 源中，定义如下自定义样式：

.. role:: style1
    :class: class1

.. role:: style2
    :class: class2

这里的“style_”是在 ReST 中引用这些的句柄，“class_”是 CSS 类名。

(2) 将上述内容用作量规中的内联样式：

.. rubric:: :style1:`fake H1`

.. rubric:: :style2:`fake H2`

(3) 在任何有意义的 CSS 文件中，为新类定义样式：

.rubric > .class1 {
    whatever
}

.rubric > .class2 {
    whatever
}

如果你愿意，这里的“whatever”可以与 H1、H2 等的现有样式相同。

注意：在第 (3) 步中，您可以更宽泛或更窄地定义 CSS 选择器。如果新的类名是全局唯一的，选择器可以像.class1 一样简单；或者，如果您只想像我的示例那样将样式用于顶级量规，则可以改用 p.rubric > span.class1。

Answer 3

Docutils，reStructuredText 的参考实现，Sphinx 在此基础上构建，允许您将选项传递给table of contents directive，它允许您控制希望目录进入文档层次结构的深度。从reStructuredText documentation，contents 指令采用depth 选项：

深度：整数

目录中收集的部分级别数。 默认为无限深度。

因此，要获得仅包含在目录中的顶级标题的文档结构，您可以使用

.. contents: Table of Contents
   :depth: 1

编辑：好像Sphinx实现了自己的table of contents directive，所以可以使用

.. toctree: Table of Contents
   :maxdepth: 1

而不是上面的第一个代码块。另外，请查看hidden 选项，这可能有助于进一步控制目录中包含的级别。