如何在Sphinx文档示例中保留NumPy的旧版字符串表示形式？

你可能已经注意到这个矛盾点：NEP 51改动了NumPy的标量字符串表示后，最新版NumPy运行np.sin(np.pi/2.)会输出np.float64(1.0)，但NumPy官方文档里的numpy.sin示例却显示1.0；SciPy的scipy.special.erfinv文档示例输出是0.4769362762044699，但实际运行最新版本会得到带类型包装的结果。这背后是专门的兼容配置，咱们分两部分说明：

一、Sphinx文档的适配方案 #

NumPy、SciPy这类科学计算库的官方文档，是在文档构建阶段自动开启了NumPy的legacy打印模式。

具体来说，它们会在Sphinx的核心配置文件conf.py，或者专门的文档初始化脚本中，提前执行np.set_printoptions(legacy="1.25")（这个参数是适配NEP 51的legacy选项）。这样当Sphinx渲染示例代码、生成对应的输出结果时，就会沿用旧版的简洁数值格式，而不会显示完整的np.float64(...)类型包装，让文档展示的内容和用户熟悉的旧版输出保持一致。

二、pytest Doctest的通过方法 #

如果你的模块需要用pytest --doctest-modules mymod命令通过文档测试，有几种实用的处理方式：

• 全局统一配置：在项目根目录的conftest.py中添加如下代码，让所有doctest在执行前自动启用旧版打印格式：

  import numpy as np
  def pytest_configure(config):
      # 开启legacy模式，匹配NEP 51之前的输出格式
      np.set_printoptions(legacy="1.25")
  

  这样所有测试用例都会沿用简洁的数值输出，和文档示例保持匹配。
• 单个测试块临时设置：如果只有部分测试需要兼容旧格式，可在对应的doctest块开头直接添加设置：

  >>> import numpy as np
  >>> np.set_printoptions(legacy="1.25")
  >>> np.sin(np.pi/2.)
  1.0
  

• Doctest模糊匹配：要是不想修改NumPy的默认行为，也可以使用doctest的ELLIPSIS选项允许部分匹配，比如：

  >>> np.sin(np.pi/2.)  # doctest: +ELLIPSIS
  1...
  

  不过这种方式不如直接设置legacy选项来得统一和直观，适合局部特殊场景。

备注：内容来源于stack exchange，提问作者Mike T