#303 Docutils 0.13 broke rstFlatTable extension used by Linux kernel documentation

[Dmitry Shachnev]

Dear docutils developers,

I got a bug report that with Docutils 0.13.1, the Linux kernel documentation fails to build. Even though it uses Sphinx, I was able to reduce it to a pure docutils example.

With the attached file (which is a slightly simplified version of original rstFlatTable.py (git.kernel.org) without the Sphinx-specific part), I get the following traceback:

>>> from docutils.core import publish_parts
>>> from docutils.parsers.rst import directives
>>> from rstFlatTable import FlatTable
>>> directives.register_directive("flat-table", FlatTable)
>>> 
>>> source_text = """
... .. flat-table:: title
... 
...    * - col 1
...      - col 2
... """
>>> publish_parts(source_text, writer_name="html")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python3/dist-packages/docutils/core.py", line 448, in publish_parts
    enable_exit_status=enable_exit_status)
  File "/usr/lib/python3/dist-packages/docutils/core.py", line 662, in publish_programmatically
    output = pub.publish(enable_exit_status=enable_exit_status)
  File "/usr/lib/python3/dist-packages/docutils/core.py", line 219, in publish
    output = self.writer.write(self.document, self.destination)
  File "/usr/lib/python3/dist-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/usr/lib/python3/dist-packages/docutils/writers/_html_base.py", line 71, in translate
    self.document.walkabout(visitor)
  File "/usr/lib/python3/dist-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3/dist-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3/dist-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3/dist-packages/docutils/nodes.py", line 166, in walkabout
    visitor.dispatch_visit(self)
  File "/usr/lib/python3/dist-packages/docutils/nodes.py", line 1882, in dispatch_visit
    return method(node)
  File "/usr/lib/python3/dist-packages/docutils/writers/html4css1/__init__.py", line 765, in visit_tbody
    self.write_colspecs()
  File "/usr/lib/python3/dist-packages/docutils/writers/html4css1/__init__.py", line 289, in write_colspecs
    width += node['colwidth']
TypeError: unsupported operand type(s) for +=: 'int' and 'str'

Do you know what could cause this error and what I can change to fix it?

[Dmitry Shachnev]

Really attaching the rstFlatTable.py file now.

[Günter Milde]

Sorry for the inconvenience. This is most likely caused by patch #120:
The table directive was extended and now also accepts/stores string values.
Also, the get_column_width() method now returns two values:
widths, col_widths = self.get_column_widths(max_cols)
See https://sourceforge.net/p/docutils/patches/120/ for details.

[Ben Hutchings]

Thanks for the explanation, but do you accept that it's not OK to break compatibility this way? The extension has to be optional.

[Günter Milde]

I accept that this is unfortunate and should be avoided if possible.
However, Docutils does not promise stability:

Docutils is in active development and APIs should be considered experimental subject to change at any time. Although any time is a time after serious thought and discussion.
-- http://docutils.sourceforge.net/

This is not an extension, but a change to the docutils core

• docutils/parsers/rst/directives/tables.py
  • Apply [ 120 ] tables accept option widths: list of relative widths, 'auto'
    or 'grid'.
    -- HISTORY.txt

The patch was accepted and integrated after testing and discussion on the docutils-devel list.
I have to admit, that I missed to spot the change in the return value of get_column_widths() and hence the opportunity to suggest a less disruptive change.

[Dmitry Shachnev]

Günter: Thanks for your response! Based on your advice, I have submitted patches to Linux and to os-api-ref to deal with this issue. So this bug can probably be closed now.

[Günter Milde]

The "colwidth-auto-safe" patch restores backwards compatibility but keeps the additions from patch 120.

[David Goodger]

If we apply this patch, won't we just break rstFlatTable again? Let's coordinate with them first. Dmitry, please comment on the best way forward.

[Günter Milde]

After the go-ahead of Dmitry, this is now fixed in [r8010].

Dmitry, could you inform the upstream parties, please?

[Dmitry Shachnev]

Dmitry, could you inform the upstream parties, please?

Done! Informed linux-doc and left a comment on my Openstack change.