For code tests, sphinx-proof uses pytest.

Run the tests with the following command:

>> cd sphinx-proof
>> pip install -e .[testing]
>> pytest

To run the tests in multiple isolated environments, you can also run tox

>> cd sphinx-proof
>> tox

To test the build of documentation run

>> cd sphinx-proof
>> tox docs-update


>> cd sphinx-proof/docs
>> make clean
>> make html

Unit Testing#

We use pytest for testing, pytest-regression to regenerate expected outcomes of test and pytest-cov for checking coverage.

To run tests with coverage and an html coverage report:

pytest -v --cov=sphinx_proof --cov-report=html

Writing Tests#

The module sphinx.testing is used to run sphinx builds for tests, in a temporary directory.

If creating a new source folder for test files, folder name should start with test-. Your folder should reside inside the tests/books directory, which has been set as the root directory for tests.

The tests should start with:

@pytest.mark.sphinx('html', testroot="mybook")

In the above declaration, html builder is used. And mybook is the source folder which was created with the name test-mybook inside tests/books folder.

Sphinx Application API is available as a parameter to all the test functions:

@pytest.mark.sphinx('html', testroot="mybook")
def mytest(app):

Code Style#

Code is formatted using black and code style is tested using flake8 with style configuration set in .flake8.

Installing using [code style] will make the pre-commit package available which will make sure the style is met before your commits are submitted. In addition, it will reformat for any lint errors.

To install pre-commit run the following

cd sphinx-proof
pre-commit install

black and flake8 can be run separately:

>>> black .
>>> flake8 .