如何解决Sphinx不识别≤、≥符号的显示异常问题

根因说明 #

符号转问号问题本质是编码不匹配：CSV文件编码、Sphinx读取CSV时的解码规则、最终HTML输出编码三者不一致导致的特殊符号解析失败。以下是优先级从高到低的解决方案：

• 方案1：统一编码配置（最优，无需修改CSV内容）

  1. 先把你的CSV文件重新保存为*UTF-8（无BOM）*格式，不要用GBK、GB2312等中文编码
  2. 在你调用CSV的csv-table指令中显式指定编码参数，示例配置如下：

  .. csv-table:: 测试数据表
     :file: ./data/your_file.csv
     :encoding: utf-8
     :header-rows: 1
  

  配置完成后重新编译，CSV中原生的≤、≥符号就能正常渲染，不需要做任何替换。

• 方案2：全局字符替换（适合需要批量统一修改符号的场景）
  如果因为业务规则不能修改CSV的存储编码，可以在Sphinx的项目配置文件conf.py中添加全局替换规则，不需要逐个修改符号：

  rst_prolog = """
  .. |le| replace:: ≤
  .. |ge| replace:: ≥
  """
  

  后续CSV中需要用≤的地方写|le|，需要用≥的地方写|ge|即可，编译时会自动替换为对应符号，可读性远高于HTML实体写法。

• 方案3：数学角色适配（适合需要多格式输出的场景）
  如果你除了HTML之外还需要输出PDF、EPUB等其他格式，直接用Sphinx内置的math角色写法：
  把CSV中的≤替换为:math:`\le` ，≥替换为:math:`\ge` ，所有输出格式都能正常渲染符号。

你当前使用的HTML实体替换方案可作为临时兜底方案，适合CSV需要同时兼容其他非Sphinx场景的情况，缺点是CSV本身的可读性会下降。

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