Sphinx doctest解决Matplotlib交互问题

本教程探讨了在Sphinx文档中，当使用`doctest`测试包含Matplotlib绘图示例的文档字符串时，如何避免交互式图形窗口中断测试流程的问题。核心解决方案是重构Matplotlib绘图函数，使其接受可选的`ax`参数，并将图形的显示控制权（即`plt.show()`的调用）交由调用者处理，从而实现无缝的自动化测试。

问题背景与分析

在使用Sphinx生成项目文档并结合doctest模块进行代码示例测试时，开发者可能会遇到一个常见问题：当函数的文档字符串中包含Matplotlib绘图示例，并且这些示例调用了plt.show()方法时，doctest的执行会被中断。plt.show()会打开一个交互式的图形窗口，这要求用户手动关闭窗口才能让doctest继续执行，这显然不符合自动化测试的需求。

问题的根源在于plt.show()的设计。它旨在显示当前活动的Matplotlib图形，并进入一个事件循环，直到图形窗口被关闭。在自动化测试环境中，这种行为会导致测试进程挂起，因为它期待用户交互。为了实现自动化测试，我们需要一种机制，既能让doctest验证绘图逻辑，又不会触发交互式窗口。

解决方案：重构Matplotlib绘图函数

解决此问题的关键在于改变Matplotlib绘图函数的结构，使其不负责图形的最终显示，而是将这一控制权交给调用者。具体而言，就是让绘图函数接受一个可选的matplotlib.axes.Axes对象作为参数，并在函数内部移除plt.show()的调用。

核心设计理念

1. 注入 Axes 对象: 绘图函数应设计为可以接收一个预先创建的Axes对象。如果未提供，函数可以自行创建一个新的Figure和Axes。
2. 移除 plt.show(): 绘图函数内部不应包含plt.show()。图形的显示应由调用者在适当的时机（例如，在脚本的顶层或交互式会话中）负责。
3. 返回 Axes 对象: 函数应返回它所操作的Axes对象，以便调用者可以进一步自定义或显示该图形。

示例代码

以下是根据上述理念重构后的plot_numbers函数：

import matplotlib.pyplot as plt

def plot_numbers(x, *, ax=None):
    """
    显示一组数字的折线图。

    Parameters
    ----------
    x : list
        要绘制的数字列表。
    ax : Axes, optional
        可选的Matplotlib Axes对象，用于在其上绘制数字。
        如果未提供，将自动创建一个新的Axes。

    Example
    -------
    >>> import calc # 假设此函数在 calc 模块中
    >>> x = [1, 2, 5, 6, 8.1, 7, 10.5, 12]
    >>> ax = calc.plot_numbers(x)
    >>> # 在实际应用中，如果需要显示，可以在此处调用 plt.show()
    >>> # 例如：plt.show()
    >>> # 为了doctest的自动化，我们不在这里调用 plt.show()
    >>> # 而是检查返回的ax对象是否有效
    >>> import matplotlib.pyplot as plt
    >>> assert isinstance(ax, plt.Axes)
    >>> # 可以进一步检查ax中的内容，例如线条数量等
    >>> assert len(ax.lines) == 1
    """
    if ax is None:
        _, ax = plt.subplots() # 如果没有提供Axes，则创建一个新的

    ax.plot(x, marker="o", mfc="red", mec="red")
    ax.set_xlabel("X轴标签")
    ax.set_ylabel("Y轴标签")
    ax.set_title("图表标题")

    return ax

代码解析与Doctest兼容性

1. ax=None 参数: 函数现在接受一个名为ax的可选关键字参数。这使得调用者可以传入一个现有的Axes对象。
2. 条件性创建 Axes: if ax is None: _, ax = plt.subplots() 这一行确保了函数既可以独立运行（自动创建Axes），也可以集成到更大的绘图布局中（使用外部传入的Axes）。
3. 移除 plt.show(): 最关键的改变是删除了原有的plt.show()调用。这意味着函数执行完毕后，不会自动弹出图形窗口。
4. 返回 ax 对象: 函数现在返回它所操作的Axes对象。这对于doctest至关重要，因为测试可以检查返回的ax对象是否是有效的Matplotlib Axes实例，甚至可以进一步检查ax上的绘图元素（例如，ax.lines属性）。
5. Doctest 自动化: 通过移除plt.show()，doctest在执行示例时将不再被图形窗口阻塞。它会执行绘图逻辑，但不会尝试显示图形。测试现在可以专注于验证函数是否正确地配置了Axes对象，而不是图形的视觉呈现。例如，示例中添加了assert isinstance(ax, plt.Axes)和assert len(ax.lines) == 1，这些断言可以在不显示图形的情况下验证函数的行为。

注意事项与最佳实践

• 库函数设计: 对于任何作为库一部分的绘图函数，通常都建议避免在函数内部调用plt.show()。plt.show()更适合在最终用户脚本或交互式会话中调用，它表示“我已完成所有绘图设置，现在请显示它”。将此职责从库函数中分离，可以提高函数的灵活性和可重用性。
• 灵活性: 允许传入ax参数极大地增加了函数的灵活性。用户可以将你的绘图集成到他们自己的Figure和Axes布局中，例如子图、多图布局等，而无需修改你的函数。
• 资源清理: 即使不调用plt.show()，Matplotlib的Figure和Axes对象仍然会被创建并占用内存。在长时间运行的测试或循环中，如果创建了大量图形而不进行清理，可能会导致内存问题。在某些高级场景中，可能需要在测试结束后显式地调用plt.close('all')来关闭所有图形。然而，对于doctest这种单次运行的示例，通常不是必须的。
• 官方文档参考: Matplotlib官方文档也推荐了类似的辅助函数（helper functions）设计模式，即接受ax参数。这是一种被广泛接受的最佳实践。

总结

通过将Matplotlib绘图函数重构为接受可选的ax参数并移除内部的plt.show()调用，我们不仅解决了Sphinx doctest在处理绘图示例时遇到的交互式图形窗口中断问题，还提升了函数的通用性和可测试性。这种设计模式使得绘图函数更加模块化，更易于集成到不同的应用场景和自动化测试流程中，是编写高质量Python绘图库的推荐实践。