如何在reStructuredText表格的行内代码中启用自动换行？

问题描述 #

我用reStructuredText编写了如下表格，尝试通过widths参数调整列宽，但渲染后表格仍超出文本宽度，且第一列布局混乱：

..
   The 'widths' is an attempt to enlarge the first row. The behavior
   stays the same without it.
.. list-table::
   :widths: 75 10 15
   :header-rows: 1

   * - Init system
     - Default location
     - Active location
   * - systemd
     - ``/usr/lib/systemd/system/``
     - ``/etc/systemd/system/multi-user.target.wants``
   * - dinit
     - ``/usr/lib/dinit.d/``
     - ``/lib/dinit.d/boot.d/``
   * - runit
     - ``/etc/sv/``
     - ``/var/service/``

渲染效果如下：

请问该如何解决这个问题？

解决方法 #

1. 调整列宽比例，适配长内容列

你当前的widths把75%宽度分配给了内容最短的第一列，反而第三列的超长路径因宽度不足溢出。建议根据内容长度重新分配比例，比如调整为20 25 55：

.. list-table::
   :widths: 20 25 55
   :header-rows: 1

   * - 初始化系统
     - 默认路径
     - 激活路径
   * - systemd
     - ``/usr/lib/systemd/system/``
     - ``/etc/systemd/system/multi-user.target.wants``
   * - dinit
     - ``/usr/lib/dinit.d/``
     - ``/lib/dinit.d/boot.d/``
   * - runit
     - ``/etc/sv/``
     - ``/var/service/``

2. 启用自动换行（针对Sphinx等渲染器）

如果使用Sphinx渲染，可以给表格添加:class: longtable类，让长文本自动换行：

.. list-table::
   :widths: 20 25 55
   :header-rows: 1
   :class: longtable

   * - 初始化系统
     - 默认路径
     - 激活路径
   * - systemd
     - ``/usr/lib/systemd/system/``
     - ``/etc/systemd/system/multi-user.target.wants``
   * - dinit
     - ``/usr/lib/dinit.d/``
     - ``/lib/dinit.d/boot.d/``
   * - runit
     - ``/etc/sv/``
     - ``/var/service/``

3. 手动拆分长路径文本

对特别长的路径，用|手动拆分换行，保持格式整齐：

.. list-table::
   :widths: 20 25 55
   :header-rows: 1

   * - 初始化系统
     - 默认路径
     - 激活路径
   * - systemd
     - ``/usr/lib/systemd/system/``
     - ``/etc/systemd/system/``\
       |multi-user.target.wants
   * - dinit
     - ``/usr/lib/dinit.d/``
     - ``/lib/dinit.d/boot.d/``
   * - runit
     - ``/etc/sv/``
     - ``/var/service/``

4. 换用table指令实现更可控布局

如果list-table仍有问题，可改用table指令配合line-block实现精准换行：

.. table::
   :widths: 20 25 55

   +---------------+---------------------------+-------------------------------------------+
   | 初始化系统    | 默认路径                  | 激活路径                                  |
   +===============+===========================+===========================================+
   | systemd       | ``/usr/lib/systemd/system/`` | | ``/etc/systemd/system/``                |
   |               |                           | | ``multi-user.target.wants``             |
   +---------------+---------------------------+-------------------------------------------+
   | dinit         | ``/usr/lib/dinit.d/``     | ``/lib/dinit.d/boot.d/``                  |
   +---------------+---------------------------+-------------------------------------------+
   | runit         | ``/etc/sv/``              | ``/var/service/``                         |
   +---------------+---------------------------+-------------------------------------------+

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