为什么我要在重组文本中编写文档测试？答案

【问题标题】：Why would I write doctests in restructured text?为什么我要在重组文本中编写文档测试？
【发布时间】：2026-02-23 13:25:01
【问题描述】：

问这个问题的另一种方式：如果我用 reST 编写 doctest，我可以将它用于 Sphinx 或其他自动文档工作吗？

背景：我不知道如何使用 Sphinx，也没有太多关于 reST 的经验，所以我想知道是否可以在除 Sphinx 之外的其他地方使用 reST 编写的文档测试？

【问题讨论】：

没什么，我不知道如何使用 Sphinx，只是读过它并且对 reST 也没有太多经验。坦率地说，我对 Sphinx 及其所需的开销有点害怕，所以我只是想知道如果我不使用 Sphinx，在 reST 中编写文档测试是否有任何好处？有什么更简单的方法可以利用我在 reST 中编写文档测试的事实吗？
我不明白你的问题：你的意思是在用 rst 编写的单独文档中包含 doctests 吗？或将 rst 添加到您的文档字符串中？文档测试不需要 rst，但文档需要。
那么为什么 doctest 文档中 doctest.testfile() 的简单用法示例然后作为 reST 文件给出？ docs.python.org/dev/library/doctest.html，第 25.2.2 节
@K.-MichaelAye 它经常一起使用，您可以使用 doctest 测试您在文档中提供的示例。另见 mzjn 的回答。

【解决方案1】：

为什么我要在重组后的文本中编写文档测试？

您并没有真正“以重组文本”编写测试。交互式示例是测试用例，与周围标记的外观无关；它可以是 reST，也可以是 Markdown 或 LaTeX 之类的其他东西。

reST 已被采用为 Python 文档的 "official" markup language，但您没有义务使用它。

那么为什么 doctest 文档中 doctest.testfile() 的简单用法示例然后作为 reST 文件给出？

Doctest 是一种通过检查文档中嵌入的交互式示例的正确性来测试代码的方法，因此examples explaining the doctest module 还包含 reST 标记是有道理的。

您可以对仅包含交互式输入/输出示例且不包含其他内容的文本文件运行 doctest。这些示例作为轻量级单元测试可能很有用，但它们本身不太适合作为文档。

我想知道是否可以在除 Sphinx 之外的其他地方使用 reST 编写的文档测试？

即使您的文档不使用 Sphinx，拥有可测试的代码示例也会很有用。

如果您正在寻找了解 reST 的替代文档工具，请查看 docutils（Sphinx 是基于它的，顺便说一句）及其front-end tools，例如 rst2html.py。

另一个可能感兴趣的工具是rst2pdf。

【讨论】：

【解决方案2】：

向文档中添加 doctest 有助于确保文档中的代码实际按预期工作。因此，您正在测试您的文档。对于一般的代码测试，根本不推荐使用 doctests。

【讨论】：