[英]How to test the validity of your Sphinx documentation?
I have a whole bunch of documentation for my Python package written using standard Sphinx .rst
files. 我有一大堆使用标准Sphinx
.rst
文件编写的Python包文档。 I also have tests for my package, among which I'd like to include a test for whether the documentation will compile properly into the expected output. 我也对我的软件包进行了测试,其中我想包括一个测试文件是否可以正确编译到预期的输出中。 Basically, I want to catch cases when I've used a link to nowhere, or have a poorly-formed header etc.
基本上,我想抓住一些情况,当我使用链接到无处,或者有一个结构不良的标题等。
Now I know that I can always write a test that calls make html
and tests for the exit code, but this feels really dirty, so I'm thinking that there must be a better way. 现在我知道我总是可以写一个调用
make html
和测试退出代码的测试,但这感觉很脏,所以我认为必须有更好的方法。 Anyone know what it is? 有人知道这是什么吗?
You could create a unit test for your documentation in the same way as you create for your code. 您可以使用与为代码创建相同的方式为文档创建单元测试。 To catch warnings you can set
warningiserror=True
in Sphinx config: 要捕获警告,您可以在Sphinx配置中设置
warningiserror=True
:
from django.utils import unittest
from sphinx.application import Sphinx
class DocTest(unittest.TestCase):
source_dir = u'docs/source'
config_dir = u'docs/source'
output_dir = u'docs/build'
doctree_dir = u'docs/build/doctrees'
all_files = 1
def test_html_documentation(self):
app = Sphinx(self.source_dir,
self.config_dir,
self.output_dir,
self.doctree_dir,
buildername='html',
warningiserror=True,
)
app.build(force_all=self.all_files)
# TODO: additional checks here if needed
def test_text_documentation(self):
# The same, but with different buildername
app = Sphinx(self.source_dir,
self.config_dir,
self.output_dir,
self.doctree_dir,
buildername='text',
warningiserror=True,
)
app.build(force_all=self.all_files)
# TODO: additional checks if needed
def tearDown(self):
# TODO: clean up the output directory
pass
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.