在 Sphinx 中使用 autodoc 时的标题答案

【问题标题】：Headings when using autodoc in Sphinx在 Sphinx 中使用 autodoc 时的标题
【发布时间】：2020-11-01 10:50:00
【问题描述】：

我有一个如下所示的文档文件：

##
H1
##

Blah Blah

**
H2
**
Blah Blah

H3
==

Blah Blah

H4
--

Blah Blah

.. automodule:: lib.X
   :members:

Python 文件X.py 如下所示：

"""
Another H3
==========

Blah Blah
"""

Lots of stuff

我的问题是X.py 中模块文档字符串的第一个标题以与原始文档H4 中的最后一个标题相同的方式呈现在 HTML 中，而不是呈现为第三级标题。我做错了什么还是我在 Sphinx 中发现了问题？

【问题讨论】：

@bad-coder，在我提供的代码中用“pass”替换“Lots of stuff”，你有一个最小的例子。唯一相关的是 doctree 包含一个 Sphinx 标头 Python 文件的其余部分与此问题完全无关。
我同意这一点，但它使 Python 模块文档字符串和 @include 文件成为二等公民。需要 Docutils 和 Sphinx 支持的一种潜在解决方案是能够声明任何已发现的听力层次结构仍然可以控制。这对在主文件中使用从属文档的问题没有任何作用。另一种解决方案是添加一个 DocUtils 指令，该指令声明从属文档中的标题与已发现的层次结构相关。因此，从属文档总是可以从级别 1 开始并且仍然适合。
您的建议适用于当前的 Sphinx 环境，如果您将其转化为答案，我可以接受。

【解决方案1】：

页面被独立解析，无需了解您在其他页面中采用的装饰符号/层次结构。 H1/H2/H3 序列为simply the order as encountered。

例如，尝试将您的 .. automodule:: 块从文档文件的底部（即遇到的第 5 个标题）移动到顶部（即第 1 个标题），它的样式将会更新。

因此，您的 Python 文件中的部分标题将在其中查看样式为 H1...或嵌入文档文件时为 H5。

【讨论】：

@bad_coder，我删除了最后一个H4，这样最后一个级别变成了H3，我的Python模块中的第一个标题被渲染为H4。我习惯于使用 Python 文档约定来标记标题，但是当您越过 automodule 边界时，标题层次结构似乎发生了一些有趣的事情。这嵌套在子公司toctree 中，但我在那个级别似乎没有任何问题。 CSS 的问题在于它依赖于正确标记的 HTML。
@bad-coder，对我来说，文档适合更广泛的环境，所以我既被不同系统的综合所吸引，也受其影响。现在我想在通过 automodule 访问的模块中使用 Sphinx 标头，因此我试图找出规则，以便例如，模块内的文档可以在具有不同标题层次结构的不同高级文档中使用。我觉得这可能是 Sphinx 的缺失部分。
我经常在 Python 模块级文档字符串中使用 reST 部分标题；没有警告或“碰撞”发生； Sphinx 通过嵌套层次结构从多个来源平静地汇总内容。 .. contents::、.. toctree::、.. include:: 指令和 HTML 侧边栏在逻辑上和您期望的一样“正常工作”。最初的问题很明确，但谈话似乎已经转移到了关于文档风格的哲学辩论。

【解决方案2】：

我认为在文档字符串中包含reST structural elements 是一种误解，即Sections（标题）和Transitions（如果您尝试，Sphinx 应该会发出警告）。不要将前者与Docstring sections 混淆。 两者都称为部分，但相似之处仅止于此。

因为，如果您想在两个不同的 .rst 文件中包含给定的模块或类，使用 autodoc 指令，文档字符串中的固定标题（结构元素）可能与.rst 文件。

这将创建一个结构约束，.rst 文件标题层次结构将取决于您在其中放置 autodoc 指令。从概念上讲，我认为结构的控制应该只依赖于.rst 文件。

另外，遇到section adornments style 定义了一个标题级别，因此autodoc 指令的不同位置最终将控制.rst 结构。（别忘了，如果您的输出是 HTML，您将被限制为 6 级标题，因此在文档字符串中使用它们会进一步限制您在 .rst... 中的结构选项。

docutils 是如何影响这个等式的？（由 OP 在 cmets 中提到。）

不用担心 docutils！一个普通的 Python 开发人员只需要 Sphinx（需要 reST）来编写好的文档。 docutils 的用途是编写 costum Sphinx 扩展，但对于大多数用途，已经提供了稳定的扩展/指令。

【讨论】：