覆盖 sphinx/docutils 中的默认字段名称限制答案

【问题标题】：Overriding the default field name limit in sphinx/docutils覆盖 sphinx/docutils 中的默认字段名称限制
【发布时间】：2012-10-13 07:29:24
【问题描述】：

我正在使用sphinx 为项目生成 html 文档。我大量使用field lists。

在生成 html 时，如果标签的长度最多为 14 个字符，则每个标签/值对将呈现为包含两个单元格的单个表格行。

如果一对标签的长度超过 14 个字符，则标签/值将呈现为两个表格行。

我想将换行限制增加到更大的值（例如 40）。我发现限制是由 docutils 的 --field-name-limit 选项控制的。但是，我找不到如何通过 sphinx 设置这个值。

我在文档根目录中创建了一个docutils.conf 文件，内容如下：

[general]
dump_settings: 1
dump_internals: 1

[html4css1 writer]
field_name_limit: 40

当我运行 sphinx 时会读取该文件。由于[general] 部分中的值，打印了设置和内部结构。在打印的值中，field_name_limit 被打印为具有值40。尽管如此，我描述的包装仍然出现在 html 输出中。

如何设置field_name_limit 的值，以便获得所需的输出？

【问题讨论】：

FWIW，在 Sphinx 版本 v 1.6.6 中，来自 docutils.conf 的设置受到尊重。

标签： python python-sphinx restructuredtext docutils

【解决方案1】：

如果没有异议，Sphinx-1.2 将支持 docutils.conf 用于 html writer。 https://bitbucket.org/birkenfeld/sphinx/commits/67682aca

【讨论】：

【解决方案2】：

我认为你的方法行不通，因为 sphinx 使用自己的 html 编写器。

但是我认为它应该可以工作，如果你适应 field_name 的风格。我（曾经）使用了一个自定义 css 文件和

.field-name {
    white-space: nowrap;
}

或将其设置为固定宽度。

【讨论】：

在 Sphinx 1.6.6 中，这种方法不可行，因为 Writer 在 2 个不同的表行中呈现字段名称和值。
这不起作用，因为包装是在docutils html writer中实现的，它会生成不同的html元素，请参阅：github.com/docutils/docutils/blob/…

【解决方案3】：

一种方法是覆盖扩展原始 html 构建器的自定义 sphinx 构建器类中的设置，并在 prepare_writing(self, docnames) 函数中设置 self.settings.field_name_limit = 0。也就是说，这有点矫枉过正，除非您已经有一个自定义构建器类...

【讨论】：