5

我正在使用 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)
###########################################################################

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

4

3 回答 3

5

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

(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改用。

于 2014-05-08T18:39:19.917 回答
3

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

深度：整数

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

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

.. contents: Table of Contents
   :depth: 1

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

.. toctree: Table of Contents
   :maxdepth: 1

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

于 2013-10-01T07:31:59.827 回答
3

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

于 2016-11-04T15:42:31.723 回答