另一种问这个问题的方法: 如果我在reST中编写doctests,我可以将它用于Sphinx或其他自动文档工作吗?
背景:我不知道如何使用Sphinx并且对reST也没有太多经验,所以我想知道我是否可以在其他地方使用rest-written doctests而不是Sphinx?
答案 0 :(得分:2)
为什么我会在重组文本中编写doctests?
您并没有真正在“重组文本”中编写测试。交互式示例是测试用例,并且周围标记的外观并不重要;它可能是reST,或者它可能是Markdown或LaTeX之类的东西。
reST已被用作Python文档的"official" markup language,但您没有义务使用它。
那么为什么doctest文档中的doctest.testfile()的简单用法示例会作为reST文件提供?
Doctest是一种通过检查文档中嵌入式交互式示例的正确性来测试代码的方法,因此examples explaining the doctest module也包含reST标记是有道理的。
您可以对仅包含交互式输入/输出示例的文本文件运行doctest,而不包含其他内容。这些示例可用作轻量级单元测试,但就其本身而言,它们不太适合作为文档。
我想知道我是否可以在其他地方使用rest-written doctests而不是Sphinx呢?
即使您没有将Sphinx用于文档,也可以使用可测试的代码示例。
如果您正在寻找了解reST的替代文档工具,请查看docutils(Sphinx基于,btw)及其front-end tools,例如rst2html.py。
可能感兴趣的另一个工具是rst2pdf。
答案 1 :(得分:0)
在文档中添加doctests有助于确保文档中的代码实际按预期工作。所以,您正在测试您的文档。对于一般的代码测试,根本不建议使用doctests。