Developers

Development of this package follows the following conventions and styles.

Design notes and considerations can be found in Design of the Package

Install

To install the package in develop mode:

cd sphinx-exercise
pip install -e .

Testing

For code tests, sphinx-exercise uses pytest.

Run the tests with the following command:

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

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

>> cd sphinx-exercise
>> tox

To test the build of documentation run

>> cd sphinx-exercise
>> tox docs-update

or

>> cd sphinx-exercise/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_exercise --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):