ReST 自定义指令的输出导致内置编写器回溯

Question

我编写了一个自定义的 ReST 指令，它接受这样的输入：

.. foo::
    abcdef
    ghijkl
    mnopqr

    a = apple; apple.png
    b = banana; banana.png
    (etc.)

并输出一个表格。桌子的形状像上面的字母块，每个字母代表一个图像。接下来的几行将图像与每个字母相关联。

这是执行输出的指令部分：

tbody = nodes.tbody()
for line in lines[:3]:
    row = []
    for c in line:
        if c not in ingredients:
            continue
        name, image = ingredients[c]
        row.append(nodes.image(uri=IMAGE_URL.format(image)))
    row_entries = [nodes.entry([n]) for n in row]
    row = nodes.row()
    row.extend(row_entries)
    tbody.append(row)

table = nodes.table()
tgroup = nodes.tgroup()
table.append(tgroup)
tgroup.append(tbody)
return [nodes.literal_block(text='\n'.join(self.content))] + table

这“有效”，因为它返回正常。但后来，当作者试图输出我的指令返回的内容时，它会导致回溯：

Traceback (most recent call last):
  File "./rst2html.py", line 24, in <module>
    publish_cmdline(writer_name='html', description=description)
  File "/usr/lib64/python3.2/site-packages/docutils/core.py", line 352, in publish_cmdline
    config_section=config_section, enable_exit_status=enable_exit_status)
  File "/usr/lib64/python3.2/site-packages/docutils/core.py", line 219, in publish
    output = self.writer.write(self.document, self.destination)
  File "/usr/lib64/python3.2/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/usr/lib64/python3.2/site-packages/docutils/writers/html4css1/__init__.py", line 173, in translate
    self.document.walkabout(visitor)
  File "/usr/lib64/python3.2/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib64/python3.2/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib64/python3.2/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib64/python3.2/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib64/python3.2/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib64/python3.2/site-packages/docutils/nodes.py", line 174, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib64/python3.2/site-packages/docutils/nodes.py", line 166, in walkabout
    visitor.dispatch_visit(self)
  File "/usr/lib64/python3.2/site-packages/docutils/nodes.py", line 1627, in dispatch_visit
    return method(node)
  File "/usr/lib64/python3.2/site-packages/docutils/writers/html4css1/__init__.py", line 792, in visit_entry
    if node.parent.parent.parent.stubs[node.parent.column]:
IndexError: list index out of range

这似乎是docutils¹ 中的一个错误；我猜我返回的表格元素不是很“格式良好”，至少对作者来说是这样。但是，似乎没有关于此的 任何 文档。 （如果有，请指点！）

有谁知道我返回的 HTML 编写器不喜欢的表节点是什么，以及我应该更改什么来修复它？

¹即使我的输出不好，也应该将比“列表索引超出范围”更好的错误发回给我。

Answer 1

我犯了两个错误：

1. 看来表真的必须有colgroups。

   for _ in range(3):
       colspec = nodes.colspec(colwidth=1)
       tgroup.append(colspec)
   

   这解决了回溯的直接问题。最终的结构看起来像这样：

    * table
      * tgroup
        * one colspec for each column.
        * tbody
          * one row for each row
            * one entry for each column. (These are the cells.)
              * The optional content for the cell. You can pass in an empty
                entry, the HTML writer will output an  'd cell.
   

   还有一个thead，用于标题；就像tbody 一样工作。我一直在使用（并最终从）docutils.parsers.rst.directives.tables 中解决了这个问题，build_table_from_list 的功能非常有用。

2. 我需要稍微调整一下返回值：

   return [nodes.literal_block(text='\n'.join(self.content))] + table
   

   那应该是[table]，而不是table：

   return [nodes.literal_block(text='\n'.join(self.content))] + [table]
   

   有趣的是，作者接受了这个错误。你会得到一张桌子，减去周围的<table> 标签。

请注意，colgroup 的 colwidth 是一个比率：三列 colwidth "1" 得到输出为三列宽度 "33%"。