python - 如何测试您的 Sphinx 文档的有效性？

Question

我有一大堆使用标准 Sphinx .rst 文件编写的 Python 包的文档。我还对我的包进行了测试，其中我想包括一个测试，以确定文档是否会正确编译成预期的输出。基本上，当我使用了无处可去的链接或标题格式不正确等时，我想捕捉到这种情况。

现在我知道我总是可以编写一个调用 make html 并测试退出代码的测试，但这感觉真的很脏，所以我认为必须有更好的方法。有人知道这是什么吗？

Answer 1

您可以像为代码创建单元测试一样为文档创建单元测试。要捕获警告，您可以在 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