如何在reStructuredText中实现两栏并排代码块以支持逐行对比

全环境兼容的原生实现 #

不需要依赖任何第三方扩展或自定义样式，依托RST标准网格表格语法即可完成分栏，所有合规的RST渲染器都能正常解析：

• 将网格表格拆分为左右两个等宽列，每列单元格内嵌入对应版本的代码块
• 可根据视觉需要调整表格边框、单元格内边距，让分栏代码块和普通代码块的样式保持统一
• 排版时注意两列单元格高度对齐，避免渲染时出现错位

示例写法：

+----------------------------------+----------------------------------+
| 旧版本实现                       | 优化后实现                       |
+==================================+==================================+
| .. code-block:: python           | .. code-block:: python           |
|   :linenos:                      |   :linenos:                      |
|                                  |                                  |
| def sum(arr):                    | def sum(arr):                    |
|     total = 0                    |     return sum(arr)              |
|     for n in arr:                |                                  |
|         total += n               |                                  |
|     return total                 |                                  |
+----------------------------------+----------------------------------+

这种方法的局限性是调整列宽需要手动数分隔线长度，长代码块的对齐调整工作量较高。

Sphinx场景的高效可响应实现 #

如果是在Sphinx生态下编写RST文档，无需手写繁琐的网格表格，可通过容器指令配合轻量CSS实现适配屏幕尺寸的分栏效果：

1. 在站点自定义静态样式文件中添加布局规则：

   .code-compare-row {
     display: flex;
     gap: 1.5rem;
     margin: 1rem 0;
   }
   .code-compare-col {
     flex: 1;
   }
   /* 小屏自动转为上下堆叠布局，避免横向溢出 */
   @media (max-width: 768px) {
     .code-compare-row {
       flex-direction: column;
     }
   }
   

2. 正文通过容器指令绑定自定义类名，分别嵌入左右两个代码块：

   .. container:: code-compare-row
   
      .. container:: code-compare-col
   
         **旧版本实现**
   
         .. code-block:: python
           :linenos:
   
           def sum(arr):
               total = 0
               for n in arr:
                   total += n
               return total
   
      .. container:: code-compare-col
   
         **优化后实现**
   
         .. code-block:: python
           :linenos:
   
           def sum(arr):
               return sum(arr)
   

   这种方式调整列宽、样式灵活度更高，还能自动适配不同尺寸的展示屏幕。如果不想手写CSS规则，也可以直接使用Sphinx生态下的成熟分栏组件扩展，通过内置指令快速划分布局区域嵌入代码块。

常见踩坑点 #

• 代码块必须开启行号渲染（添加:linenos:参数），才能实现逐行对照的对比效果
• 不要用嵌套定义列表实现分栏，RST解析时极易出现层级嵌套错乱
• 对比类分栏要给两列设置相同的垂直对齐属性，保证两个代码块顶部齐平

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