How to test the validity of your Sphinx documentation?

Question

I have a whole bunch of documentation for my Python package written using standard Sphinx .rst files. 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. Anyone know what it is?

Answer 1

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:

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