将 Sphinx doctest 与包含 Matplotlib 示例的文档字符串结合使用

Question

下面所示的函数使用 Matplotlib 显示线图。该函数的文档字符串包含使用该函数与数字列表的示例。我正在使用 Sphinx

make html

命令为此函数创建文档。我还使用 Sphinx 使用

make doctest

来测试文档字符串。但是，doctest 在测试此函数时会暂停，因为它显示一个包含绘图的窗口。我必须手动关闭绘图窗口才能使 doctest 继续运行。有没有更好的方法将 doctest 与包含 Matplotlib 示例的文档字符串一起使用？

import matplotlib.pyplot as plt

def plot_numbers(x):
    """
    Show a line plot of numbers.

    Parameters
    ----------
    x : list
        Numbers to plot.

    Example
    -------
    >>> import calc
    >>> x = [1, 2, 5, 6, 8.1, 7, 10.5, 12]
    >>> calc.plot_numbers(x)
    """
    _, ax = plt.subplots()
    ax.plot(x, marker="o", mfc="red", mec="red")
    ax.set_xlabel("Label for x-axis")
    ax.set_ylabel("Label for y-axis")
    ax.set_title("Title of the plot")

    plt.show()

Answer 1

理想情况下，您可以构建绘图例程，以便用户可以提供自己的轴（和/或图形）。我不会为用户打电话

plt.show

- 你怎么知道他们已经准备好显示图形？

import matplotlib.pyplot as plt

def plot_numbers(x, *, ax=None):
    """
    Show a line plot of numbers.

    Parameters
    ----------
    x : list
        Numbers to plot.
    ax: Axes
        Optional Matplotlib Axes to plot the numbers on.

    Example
    -------
    >>> import calc
    >>> x = [1, 2, 5, 6, 8.1, 7, 10.5, 12]
    >>> calc.plot_numbers(x)
    """
    if ax is None:
        _, ax = plt.subplots() 
    ax.plot(x, marker="o", mfc="red", mec="red")
    ax.set_xlabel("Label for x-axis")
    ax.set_ylabel("Label for y-axis")
    ax.set_title("Title of the plot")

    return ax

另请参阅https://matplotlib.org/stable/users/explain/quick_start.html#making-a-helper-functions尽管在该建议中请注意，

ax

是必需的。