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


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 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
  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
  File "/usr/lib/python3/dist-packages/docutils/writers/_html_base.py", line 71, in translate
  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
  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
  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

    Dmitry Shachnev - 2016-12-16

    Really attaching the rstFlatTable.py file now.

  • Günter Milde

    Günter Milde - 2016-12-17

    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.

    Last edit: Günter Milde 2016-12-17
    • Ben Hutchings

      Ben Hutchings - 2016-12-18

      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

        Günter Milde - 2016-12-18

        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.

        Last edit: Günter Milde 2016-12-18
    • Dmitry Shachnev

      Dmitry Shachnev - 2016-12-19

      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

    Günter Milde - 2016-12-22

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

    • David Goodger

      David Goodger - 2016-12-23

      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

    Günter Milde - 2017-01-03
    • status: open --> closed-fixed
  • Günter Milde

    Günter Milde - 2017-01-03

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

    Dmitry, could you inform the upstream parties, please?



    Commit: [r8010]

    • Dmitry Shachnev

      Dmitry Shachnev - 2017-01-04

      Dmitry, could you inform the upstream parties, please?

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


Log in to post a comment.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks