Overriding the default field name limit in sphinx/docutils

Question

I am using sphinx for generating html documentation for a project. I make extensive use of field lists.

When generating html, each label/value pair is rendered as a single table row with two cells if the lenght of the label is at most 14 characters.

If the label of one pair is longer than 14 characters, the label/values are rendered as two table rows.

I want to increase the wrapping limit to a larger value (e.g. 40). I have found that the limit is controlled by the --field-name-limit option of docutils. However, I can't find how to set this value through sphinx.

I have created a docutils.conf file in the documentation root with the following contents:

[general]
dump_settings: 1
dump_internals: 1

[html4css1 writer]
field_name_limit: 40

The file is read when I run sphinx. The settings and internals are printed - because of the values in the [general] section. Among the printed values, field_name_limit is printed to have value 40. Despite all that, the wrapping I described still occurs in the html output.

How do I set the value of field_name_limit so that I get the desired output?

FWIW, in Sphinx version v 1.6.6 the setting from docutils.conf is respected. — collapsar, Jan 17 '18 at 13:15

score 3 · Answer 1 · answered Jul 26 '13 at 14:51

3

Sphinx-1.2 will support docutils.conf for html writer if no objection. https://bitbucket.org/birkenfeld/sphinx/commits/67682aca

answered Jul 26 '13 at 14:51

Takayuki SHIMIZUKAWA

297
1
10

bmu · Answer 2 · 2012-11-20T18:16:05.800

0

I think your approach doesn't work because sphinx uses its own html writer.

However I think it should work, if you adapt the style for field_name. I (once) used a custom css file with

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

or set it to a fixed width.

edited Nov 20 '12 at 18:16

answered Nov 13 '12 at 10:39

bmu

35,119
13
91
108

In Sphinx 1.6.6 that approach would not be viable as the Writer renders field name and value in 2 different table rows. – collapsar Jan 17 '18 at 13:16
This doesn't not work because the wrapping is implemented in docutils html writer, which generates a different html elements, see: https://github.com/docutils/docutils/blob/84f7b36275804d110e05ac75688960e6f340e698/docutils/docutils/writers/html4css1/__init__.py#L916 – marbu Feb 14 '18 at 21:41

score 0 · Answer 3 · answered Feb 14 '18 at 18:54

One way to do this is to override the setting in custom sphinx builder class extending original html builder, and set self.settings.field_name_limit = 0 in prepare_writing(self, docnames) function. That said, this is a little overkill, unless you already have a custom builder class ...

Overriding the default field name limit in sphinx/docutils

3 Answers3

Linked