如何在Sphinx文档的CSV表格中实现单元格文本换行？

• 提升CSS样式优先级
  之前的CSS未生效大概率是优先级不足，直接在Sphinx项目的_static/custom.css中添加高优先级样式：

  .docutils.table {
      table-layout: fixed !important;
      width: 100% !important;
  }
  .docutils.table td:nth-child(3) {
      word-wrap: break-word !important;
      white-space: pre-wrap !important;
      max-width: 50%;
  }
  

  同时在项目的conf.py中确保加载该自定义CSS：

  html_css_files = [
      'custom.css',
  ]
  

• 给csv-table绑定专属样式类
  为目标表格添加自定义类，实现精准控制：

  .. csv-table:: xyz
          :header-rows: 1
          :file: path/file.csv
          :widths: 20, 30, 50
          :class: wrap-significance-col
  

  接着在custom.css中针对该类编写样式：

  .wrap-significance-col {
      table-layout: fixed;
      width: 100%;
  }
  .wrap-significance-col td:nth-child(3) {
      word-wrap: break-word;
      white-space: pre-wrap;
  }
  

• 批量预处理CSV文件
  若CSS方案仍不奏效，可通过脚本批量给CSV第三列的长文本插入软换行符（\n），示例Python脚本：

  import csv
  import os
  
  def wrap_long_text(csv_path, col_index=2, wrap_length=50):
      with open(csv_path, 'r', encoding='utf-8') as f:
          reader = csv.reader(f)
          rows = list(reader)
      # 处理表头外的所有行
      for row in rows[1:]:
          if len(row) > col_index:
              text = row[col_index]
              # 按指定长度拆分文本并添加换行
              wrapped_text = '\n'.join([text[i:i+wrap_length] for i in range(0, len(text), wrap_length)])
              row[col_index] = wrapped_text
      # 写回处理后的内容
      with open(csv_path, 'w', encoding='utf-8', newline='') as f:
          writer = csv.writer(f)
          writer.writerows(rows)
  
  # 批量处理指定目录下的所有CSV文件
  for root, _, files in os.walk('path/to/your/csv/directory'):
      for file in files:
          if file.endswith('.csv'):
              wrap_long_text(os.path.join(root, file))
  

  处理后的CSV导入csv-table时会自动识别换行符实现文本换行，无需手动添加分隔符。

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