重组文本页面中的非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

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

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

.. role:: style1
    :class: class1

.. role:: style2
    :class: class2

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

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

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

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

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

.rubric > .class1 {
    whatever
}

.rubric > .class2 {
    whatever
}

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

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

Answer 2

Docutils是 reStructuredText 的参考实现，Sphinx 是在它的基础上构建的，它允许您将选项传递给目录指令，从而允许您控制目录进入文档层次结构的深度。从reStructuredText 文档中，该contents指令采用一个depth选项：

深度：整数

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

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

.. contents: Table of Contents
   :depth: 1

编辑：Sphinx 似乎实现了自己的目录指令，因此您可以使用

.. toctree: Table of Contents
   :maxdepth: 1

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