升级至Sphinx 7.0.1后，未定义宽度的list-table缺失colgroup标签求助

功能移除确认 #

Sphinx 7.x版本确实移除了自动为未指定宽度的list-table生成colgroup标签的逻辑，这个调整属于HTML渲染层的底层变更，没有在官方变更日志里单独说明。

修复方案 #

1. 手动指定列宽（最直接） #

在list-table的指令参数里添加:widths:配置，强制设置等宽比例，这样Sphinx会重新生成colgroup标签：

list-table::
   :header-rows: 1
   :widths: 1 1 1  # 三列等宽，比例按需调整
   
   * - Option A
     - Item B
     - Item C

   * - Option B
     - Item D
     - Item E

2. 自定义CSS全局修复 #

如果不想逐个修改rst文件，可以在项目的自定义CSS文件中添加以下样式，强制表格使用固定布局并均分列宽：

/* 针对list-table生成的表格 */
table.docutils {
    table-layout: fixed;
    width: 100%;
}
table.docutils td, table.docutils th {
    width: 33.33%;  /* 列数为3时的比例，根据实际列数调整 */
}

将这段CSS放到Sphinx配置的html_static_path指定目录下，再在html_css_files中引入即可生效。

3. 自定义Sphinx扩展（全局自动处理） #

如果需要批量处理所有未指定宽度的list-table，可以写一个简单的扩展，在HTML节点生成阶段自动插入colgroup：

from sphinx.writers.html5 import HTML5Translator

def setup(app):
    def add_colgroup(self, node):
        # 仅处理未指定宽度的list-table
        if not node.get('widths') and node.tagname == 'table':
            col_count = len(node[0][0])  # 获取表头列数
            colgroup = self.starttag(node, 'colgroup')
            for _ in range(col_count):
                colgroup += self.starttag(node, 'col', style=f'width: {100/col_count}%') + '</col>'
            colgroup += '</colgroup>'
            self.body.append(colgroup)
        # 调用原方法处理表格
        self.visit_table(node)
    
    # 替换原有的表格渲染方法
    HTML5Translator.visit_table = add_colgroup
    return {'version': '0.1', 'parallel_read_safe': True}

将这个扩展文件放到项目目录中，在conf.py的extensions列表里添加该扩展的文件名即可。

内容的提问来源于stack exchange，提问作者ms3300