Overriding the default field name limit in sphinx/

问题:

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?

回答1:

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

回答2:

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.

回答3:

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 ...