使用Sphinx能否让Python文档字符串中的示例代码自动运行并输出？

你说的这种“让Sphinx自动运行文档里的代码并生成输出”的需求，正好是Sphinx自带的sphinx.ext.doctest扩展的拿手好戏——它能帮你自动执行文档字符串里的代码片段，把运行结果直接整合到生成的文档中，完全不用手动敲输出内容。下面我给你一步步拆解怎么配置和使用：

第一步：启用doctest扩展 #

首先，打开你的Sphinx项目根目录下的conf.py文件，找到extensions列表，把sphinx.ext.doctest加进去：

extensions = [
    'sphinx.ext.autodoc',  # 如果你用自动生成文档的功能，这个通常也会加
    'sphinx.ext.doctest',  # 就是这个核心扩展！
]

# 可选配置：全局导入你的库或常用模块，避免每个代码块重复写导入
doctest_global_setup = """
import your_python_library as ypl  # 替换成你的库名
import numpy as np  # 如果你的代码用到numpy这类库，也可以提前导入
"""

另外，别忘了在conf.py里设置好路径，让Sphinx能找到你的Python库：

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # 根据你的项目结构调整路径，确保能导入你的库

第二步：在文档字符串里写可运行的代码块 #

有两种常用的写法，你可以根据需求选：

写法一：模拟Python交互式终端的示例 #

这种写法很像平时在Python shell里敲代码的样子，用>>>开头表示输入，下一行是预期输出。Sphinx会自动运行这些代码，验证输出是否和你写的一致，同时在文档里展示完整的输入输出流程：

def calculate_average(numbers):
    """计算列表中数字的平均值

    >>> calculate_average([1, 2, 3, 4, 5])
    3.0
    >>> calculate_average([10, 20, 30])
    20.0
    """
    return sum(numbers) / len(numbers)

这种写法的好处是既能做文档示例，又能顺便做单元测试——如果代码运行结果和你写的输出不一致，Sphinx构建时会抛出警告，帮你及时发现问题。

写法二：独立代码块+自动生成输出 #

如果你想展示一段完整的代码脚本，然后自动生成它的运行结果，可以用.. testcode::和.. testoutput::指令：

def greet(name):
    """向指定用户打招呼

    示例用法：

    .. testcode::
        # 导入函数
        from mylibrary import greet
        # 调用函数并打印结果
        print(greet("Alice"))
        print(greet("Bob"))

    .. testoutput::
        Hello, Alice!
        Hello, Bob!
    """
    return f"Hello, {name}!"

如果不想手动写testoutput里的内容，你可以先运行sphinx-build -b doctest . _build/doctest，Sphinx会自动生成正确的输出结果，你直接复制到testoutput块里就行；或者如果你用的是较新版本的Sphinx，还可以配置doctest_fix = True，让它自动帮你填充输出内容。

第三步：构建文档 #

最后，像平时一样运行Sphinx构建命令：

sphinx-build -b html docs/source docs/build

打开生成的HTML文档，你就能看到代码块和对应的运行结果已经自动展示出来了！

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