如何在Sphinx中执行make doctest时向doctest传递参数？

• 问题根源：SPHINXOPTS="-f"无效是因为-f是原生doctest的参数，而非sphinx-build的参数，Sphinx的doctest扩展不会直接识别这个参数。

• 实现仅测试单个文件：
  在执行make doctest时，通过SPHINXOPTS指定要测试的文件路径，比如：

  make doctest SPHINXOPTS="docs/your_debug_file.rst"
  

  这样就只会运行目标文件里的代码示例测试。

• 实现首个错误即终止：
  需要修改Sphinx配置文件conf.py，添加doctest_fast_fail = True，这个配置项会让doctest在遇到第一个错误时就停止运行。

• 组合用法：
  先在conf.py中开启快速失败，然后指定单个文件测试：

  make doctest SPHINXOPTS="docs/your_debug_file.rst"
  

  或者不想修改配置文件的话，临时通过-D参数传递配置：

  make doctest SPHINXOPTS="-D doctest_fast_fail=True docs/your_debug_file.rst"
  

• 替代方案：直接用原生doctest调试
  如果只是验证.rst里的代码示例，也可以把示例提取成单独的.py文件，用原生doctest命令直接跑：

  python -m doctest -f your_debug_code.py
  

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