sphinx 可以根据实际实施验证文档吗

Question

我正在向几个项目添加 sphinx 文档，但我担心未来的开发人员在方法接口更改时不会严格更新文档。有没有办法让 sphinx 根据方法定义中实际指定的内容来验证所描述的参数列表？

例如，假设我使用 sphinx-quickstart 设置了 sphinx，添加了 autodoc，并尝试构建以下“模块”：

def product(arg_one, arg_two):
    '''
    :param arg_one: an object to be multiplied by arg_two
    :type arg_one: Object

    :param arg_two: an integer which defines the number of arg_one to return
    :type arg_two: integer

    :returns: The product of arg_one and arg_two

    :raises: TypeError
    '''
    return arg_one * arg_two

并且，一周后，Bob Doe 更新产品如下：

def product(value, number, catch_errors=False):
    '''
    :param arg_one: an object to be multiplied by arg_two
    :type arg_one: Object

    :param arg_two: an integer which defines the number of arg_one to return
    :type arg_two: integer

    :returns: The product of arg_one and arg_two

    :raises: TypeError
    '''
    try:
        return value * number
    except TypeError as exc:
        if catch_errors:
            return None
        raise

现在，sphinx 文档不正确 - 它缺少新的 catch_errors 字段，并且变量已被重命名。但是，跑步

sphinx-build . ./_build

第二次没有发现问题 - 它只是报告

Running Sphinx v1.6.5
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

我期望（或希望）Sphinx 能够根据方法的实际代码验证文档字符串，并在文档和实现不同步时失败（或至少以某种方式表明）。

如果 sphinx 无法做到这一点，是否有替代方案？我知道 Python 3 中有 函数注释，但我们目前支持 Python 2 和 Python 3，所以这不是一个选项。

Answer 1

经过一番研究，我认为我能轻松找到的最接近的工具是darglint，但它最近在 GitHub 上进入了存档模式（2022 年 12 月），因此无法保证甚至不可能提供长期支持。

受 torchvision 的 this 讨论启发，一个选项是使用 Sphinx-Napoleon 和 pydocstyle ，几乎所有功能都关闭，除了

D417

，它用于检查文档字符串中缺少的参数。

因此

pydocstyle

可以检查 missing 参数，但目前无法检查额外参数。

编辑：似乎 pylint 可以通过扩展来做到这一点https://pylint.pycqa.org/en/latest/user_guide/checkers/extensions.html#pylint-extensions-docparams但是各种 linter 之间存在一些功能重叠和风格检查，所以你可能需要选择你要搭配的。

为了捕获重命名的参数，您还可以在测试中强制执行 100% 覆盖率，但这不会捕获对非关键字参数的重构。

其他一些可用的套餐：

doctest 非常适合检查文档字符串示例是否正确运行，但它不进行任何签名验证。因此，如果您设置像问题中的示例那样的默认参数，它仍然会通过 doctest。如果您在所有示例中都使用了关键字参数，则可以使用它作为检查，但它有点冗长。

interrogate 能够检查文档字符串覆盖率，但除此之外没有太多功能（据我所知？）我不确定其他工具是否真的可以检查覆盖率，所以这可能是一个可以串联使用的好工具。