Merge pull request #714 from fxfitz/issue712

chore(docs): Adds automated sphinx builds to tox and travis

.travis.yml

@@ -39,6 +39,8 @@ matrix:
           env: TOXENV=py35
         - python: 3.5
           env: TOXENV=py35_cython
+        - python: 2.7
+          env: TOXENV=docs
 
 script: travis_scripts/run_tests.sh
 notifications:

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 ## Contributing
 
-Hi, thanks for your interest in the project! We welcome pull requests from developers of all skill levels. 
+Hi, thanks for your interest in the project! We welcome pull requests from developers of all skill levels.
 
 Kurt Griffiths (kgriffs) is the creator and current maintainer of the Falcon framework, along with a group of talented and stylish volunteers. Please don't hesitate to reach out if you have any questions, or just need a little help getting started.
 
@@ -35,29 +35,20 @@ This generates an HTML coverage report that can be viewed by simply opening `.co
 
 ### Documentation
 
-To check documentation changes (including docstrings), before submitting a PR, do the following:
+To check documentation changes (including docstrings), before submitting a PR, ensure the tox job
+builds the documentation correctly:
 
 ```bash
-#
-# Create a virtualenv, then inside that env:
-#
-
-$ pip install -r tools/doc-requires
-$ cd doc
-$ make html
-
-#
-# Then open _build/html/index.html
-#
+$ tox -e docs
 
 # OS X
-$ open _build/html/index.html
+$ open doc/_build/html/index.html
 
 # Gnome
-$ gnome-open _build/html/index.html
+$ gnome-open doc/_build/html/index.html
 
 # Generic X Windows
-$ xdg-open _build/html/index.html
+$ xdg-open doc/_build/html/index.html
 ```
 
 ### Code style rules

tools/doc-requires

@@ -2,4 +2,5 @@ jinja2
 pygments
 docutils
 markupsafe
+sphinx
 sphinxcontrib-napoleon

tox.ini

@@ -12,6 +12,7 @@ envlist = py26,
           py34,
           pep8,
           pylint,
+          docs
 
 [testenv]
 deps = -r{toxinidir}/tools/test-requires
@@ -188,3 +189,14 @@ commands = falcon-bench []
 [testenv:pypy3_bench]
 deps = -r{toxinidir}/tools/bench-requires
 commands = falcon-bench []
+
+# --------------------------------------------------------------------
+# Documentation
+# --------------------------------------------------------------------
+[testenv:docs]
+deps = -r{toxinidir}/tools/doc-requires
+whitelist_externals = rm
+basepython = python2.7
+commands =
+    rm -rf doc/_build/*
+    sphinx-build -b html doc doc/_build/html