使用预提交挂钩自动化您的 Python 代码文档
使用预提交钩子自动化文档字符串检查和自动生成文档的实践指南
当时间很短时，代码文档通常是最先受到影响的事情。然而，高质量的代码文档对于在开发团队中有效协作、在新开发人员加入时简化入职以及在团队成员决定离开公司时确保连续性至关重要。在这篇博文中，我们将研究使用 docstrings 为您团队的 Python 项目自动生成代码文档。
使用 Docstrings 约定……并强制执行
自动化文档的第一步包括（不幸的是）手动步骤：与您的团队就文档字符串约定达成一致，并在整个代码中一致地应用该标准。
但首先，什么是文档字符串？
Docstrings 是首先放置在代码中的函数、类和方法定义中的字符串。它们通常出现在一行上，并以三引号符号开头。文档字符串用于记录函数、类和方法的用途，以及它们接受的参数和返回的参数。在 Python 中，除了少数例外，所有函数、类和方法都应该有文档字符串。[0]
存在许多不同的 Docstrings 标准，但在 Python 中一些最常用的标准包括 reStructuredText、Numpydoc、Googledoc 和 EpyText。[0][1][2][3]
虽然您仍然需要自己编写好的文档字符串来开发代码（除非您使用 GitHub Copilot），但大多数 IDE 会一路帮助您。 PyCharm——我选择的 Python IDE——会在你定义一个函数或类之后自动生成一个文档字符串存根，并预填充类型注释。您可以设置要使用的文档字符串约定，或使用您自己的模板（见下图）。[0][1][2]
一旦您的团队就文档字符串约定达成一致，建议配置预提交挂钩以检查该约定是否得到一致应用（并使它们成为您的持续集成管道的一部分，例如 GitHub Actions 或 AWS CodeBuild）。[0][1][2]
预提交挂钩是您在每次提交时运行的小“脚本”，用于识别，有时甚至自动修复代码问题。它们有许多不同的风格，可用于例如强制代码样式、修复格式问题或分析代码的复杂性。[0][1][2]
如果您想了解有关预提交钩子以及如何使用它们的更多信息，请查看下面的帖子。 👇
当团队在自己的机器上本地开发代码时，为文档字符串使用预提交钩子可以让他们保持一致。当您在持续交付框架中工作时，它们特别有用，其中团队成员需要经常进行较小的更改，并且您需要跟上快速的开发和审查周期。
幸运的是，有很多工具可以帮助您的团队跟踪他们是否正确地使用了文档字符串。
让我们快速浏览几个选项。
Interrogate
首先，interrogate 是一个有用的工具，它可以让您知道您是否未能为任何类或函数添加文档字符串。您可以在 .pre-commit-config.yaml 文件中使用以下语法将询问添加到预提交挂钩：[0]
–fail-under 标志设置工具报告故障的截止时间，而 –verbose 标志确保将详细的覆盖率报告打印到控制台。在上面显示的配置中，如果少于 80% 的代码被覆盖（带有文档字符串），询问“测试”将失败。您还可以在 pyproject.toml 文件中配置许多其他选项，以确保询问符合您的特定需求。而且，如果你和我一样喜欢在你的存储库中添加徽章，你会很高兴知道 interrogate 有这个选项。[0][1]
一旦你设置了 pre-commit 钩子并进行了新的提交（或运行 pre-commit run），interrogate 将提供一个覆盖率报告：
如您所见，我在这里一直很懒惰，完全没有为我的任何函数编写文档字符串。而且，审问正确地抱怨说我没有达到（配置的）80% 的临界值。
Pydocstyle
其次，您可能会发现 Pydocstyle 是一个有用的工具，可以包含在您的预提交挂钩中。 .pre-commit-config.yaml 文件中的配置应遵循以下格式：[0]
运行钩子（预提交运行）时，发现的任何错误都将打印回控制台，例如：
您有足够的灵活性来定制 Pydocstyle 以满足您的需求，您可以选择忽略大量错误代码。在上面的示例中，我决定禁用错误代码 D107 和 D204 的警告，这意味着我将允许在 __init__ 文件中缺少文档字符串，并在文档字符串之后缺少一个空行。[0]
Other options
其他值得包含在预提交配置中的选项包括：
- check-docstring-first pre-commit 钩子，顾名思义，它将检查您的文档字符串是否实际位于代码之前[0]
- docformatter，它将自动重新格式化文档字符串以遵循 PEP 257 标准；[0]
- velin 预提交钩子，它将尝试重新格式化您的文档字符串以遵循 numpydoc 标准。[0]
从 Docstrings 自动生成文档
现在我们已经介绍了我们的文档字符串，我们可以使用它们来自动生成文档并使其在一个地方可用。同样，有很多选择需要考虑。
在下面的示例中，我们将使用 pdoc3，它从文档字符串（来自活动对象的 __doc__ 属性）为您的类、模块、函数和变量生成文档。作为额外的奖励，如果您使用公认的分隔符，它会正确解析 LaTex 语法（非常适合数据科学、机器学习和其他数学密集型项目！）。[0][1][2][3][4]
让我们快速看一下 pdoc3 的预提交配置示例。在下面的示例中，我已将 pdoc3 设置为为名为 cosine_utils 的模块自动生成文档。我已将其配置为输出 html 文档（pdoc3 还支持纯文本和 PDF 输出）。
运行此预提交挂钩将生成一个名为 html 的文件夹，其中将包含自动生成的文档。您将能够在您选择的浏览器中查看文档，其中将包含一个格式良好的索引，显示文档对象、源代码以及您包含在文档字符串中的信息。
从文档字符串自动生成文档的其他选项包括，例如，Pydoc、Sphinx，以及我自己对文档生成器 Markdowndocs 的尝试。后者可以使用预提交挂钩设置，以将降价样式的文档（基于您的 Docstrings 和代码）添加到您的项目 README（有关更多详细信息，请参阅此 repo，有关生成文档的示例，请参阅此文件）。[0][1][2][3][4]
除了强制执行特定的文档字符串样式和自动检查之外，在您的团队中拥有良好的代码文档实践也很重要。我喜欢尝试（尽管我并不总是成功！）编写文档字符串时的想法是，当我的同事需要使用现有模块或服务时，他们应该能够通过阅读我的代码来自行开发。如果团队中的每个人都参与编写干净的代码，并附有清晰和描述性的变量和类名，以及匹配的文档字符串，那么你的开发工作就会变得更加容易。
感谢您的阅读！
如果你喜欢这篇文章，这里还有一些你可能会喜欢的文章👇
文章出处登录后可见！
