在sphinx/docutils中覆盖默认字段名称限制

Question

我使用sphinx为项目生成html文档，并大量使用字段列表。

生成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的值，以获得期望的输出？

- m000

---

就此而言，在Sphinx版本v1.6.6中，将遵守来自docutils.conf的设置。 - collapsar

Answer 1

Sphinx-1.2将支持docutils.conf用于HTML编写器，如果没有反对意见。https://bitbucket.org/birkenfeld/sphinx/commits/67682aca

- Takayuki SHIMIZUKAWA

Answer 2

我认为你的方法不起作用，因为sphinx使用自己的HTML编写器。

但是，如果你适应field_name的样式，我认为它应该可以工作。 我曾经使用过自定义的CSS文件。

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

或将其设置为固定宽度。

- bmu

---

在Sphinx 1.6.6中，该方法不可行，因为Writer会将字段名和值呈现在2个不同的表行中。 - collapsar

这不起作用是因为包装是在docutils html writer中实现的，它生成了不同的HTML元素，请参见：https://github.com/docutils/docutils/blob/84f7b36275804d110e05ac75688960e6f340e698/docutils/docutils/writers/html4css1/__init__.py#L916 - marbu

Answer 3

一种实现方法是在继承原始html构建器的自定义sphinx构建器类中覆盖设置，然后在prepare_writing(self,docnames)函数中设置self.settings.field_name_limit = 0 。话虽如此，这有点过头了，除非您已经有了自定义的构建器类...

- marbu