Have Travis-CI test your Sphinx docs

Consider you are running a project that happens to use Sphinx.

It might be a Python project, as Sphinx is popular in Python, or it might be a standalone project that simply likes the way Sphinx stitches everything together.

We use Sphinx to document the OpsSchool project - a collaborative effort by many to put together a comprehensive curriculum.
You can also see Sphinx in action at the Opscode Chef Documentation site - this uses more stylings and templates.

An important part of being open source is being able to accept contributions from others.
When you accept them, you typically want to ensure that they don't break anything else.

In software, it is common to have a test suite - be they unit, integration or acceptance tests, but it is commonly accepted that you test your changes before committing them to others.

Using a hosted testing service, such as Travis CI is perfect for open source projects on Github, as when someone forks your branch, and submits a pull request, Travis by default will run your tests.
If a pull request has been submitted and fails with any warnings or errors, Travis will let them know, so they can correct it and submit again.

Here's a sample of one of the .travis.yml configuration files I use:

language: python
python:
  - "2.7"
# command to install dependencies
install: "pip install -q -r requirements.txt --use-mirrors"
# command to run tests
script: sphinx-build -nW -b html -d _build/doctrees . _build/html
# Flags used here, not in `make html`:
#  -n   Run in nit-picky mode. Currently, this generates warnings for all missing references.
#  -W   Turn warnings into errors. This means that the build stops at the first warning and sphinx-build exits with exit status 1.

The requirements.txt file I have right now contains one line - Sphinx==1.1.3 for this project, but may contain other packages if your project needs them.

Enabling your repo for testing on Travis is really simple - you log into their interface, see your profile, and toggle a button.

This is the best way I've found to encourage others to contribute to your documentation, and giving you the confidence to merge in their code.

If you've got other ways of doing this, please let me know!