Question

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

有没有办法在页面中格式化标题而不成为TOC的一部分？理想情况下，某些层次结构会反映在格式化中吗？

E.g。我想做

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

这里＆＃34;风格_＆＃34;是在ReST中引用这些的句柄，＆＃34; class _＆＃34;是CSS类名。

（2）在rubrics中使用上面的内联样式：

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

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

（3）无论CSS文件有意义，都要为新类定义样式：

.rubric > .class1 {
    whatever
}

.rubric > .class2 {
    whatever
}

这里＆＃34;无论什么＆＃34;如果你愿意，可以与H1，H2等的现有样式相同。

注意：在步骤（3）中，您可以更广泛或更窄地定义CSS选择器。如果新类名全局唯一，则选择器可以像.class1一样简单;或者如果您想将该样式仅用于我的示例中的顶级规则，则可以使用p.rubric > span.class1代替。

Answer 2

Docutils，构建Sphinx的reStructuredText的参考实现允许您将选项传递给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选项，这可能有助于进一步控制目录中包含的级别。

Answer 3

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

Restructuredtext页面中的非TOC标题

3 个答案: