Move sphinx build functionality to tox

Currently the CI and the docs both have to duplicate the same inforation
about how to gather dependencies etc, and have to use hacky ways to run
them.

Add a new `docs` environment to our tox setup so that building docs is
as simple as running `tox -e docs`.

3 files changed, 33 insertions, 31 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 50bddd76c..7cec8d1ed 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -154,20 +154,13 @@ tests-fedora-missing-deps:
 
 # Automatically build documentation for every commit, we want to know
 # if building documentation fails even if we're not deploying it.
-# Note: We still do not enforce a consistent installation of python3-sphinx,
-#       as it will significantly grow the backing image.
 docs:
   stage: test
+  variables:
+    BST_FORCE_SESSION_REBUILD: 1
   script:
-  - export BST_SOURCE_CACHE="$(pwd)/cache/integration-cache/sources"
-  # Currently sphinx_rtd_theme does not support Sphinx >1.8, this breaks search functionality
-  - pip3 install sphinx==1.7.9
-  - pip3 install sphinx-click
-  - pip3 install sphinx_rtd_theme
-  - cd dist && ./unpack.sh && cd buildstream
-  - make BST_FORCE_SESSION_REBUILD=1 -C doc
-  - cd ../..
-  - mv dist/buildstream/doc/build/html public
+  - env BST_SOURCE_CACHE="$(pwd)/cache/integration-cache/sources" tox -e docs
+  - mv doc/build/html public
   except:
   - schedules
   artifacts:
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 669a3e486..a8425f0a7 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1222,27 +1222,13 @@ For further information about using the reStructuredText with sphinx, please see
 
 Building Docs
 ~~~~~~~~~~~~~
-The documentation build is not integrated into the ``setup.py`` and is
-difficult (or impossible) to do so, so there is a little bit of setup
-you need to take care of first.
-
-Before you can build the BuildStream documentation yourself, you need
-to first install ``sphinx`` along with some additional plugins and dependencies,
-using pip or some other mechanism::
-
-  # Install sphinx
-  pip3 install --user sphinx
-
-  # Install some sphinx extensions
-  pip3 install --user sphinx-click
-  pip3 install --user sphinx_rtd_theme
-
-  # Additional optional dependencies required
-  pip3 install --user arpy
+Before you can build the docs, you will end to ensure that you have installed
+the required :ref:`buid dependencies <contributing_build_deps>` as mentioned
+in the testing section above.
 
 To build the documentation, just run the following::
 
-  make -C doc
+  tox -e docs
 
 This will give you a ``doc/build/html`` directory with the html docs which
 you can view in your browser locally to test.
@@ -1260,9 +1246,10 @@ will make the docs build reuse already downloaded sources::
 
   export BST_SOURCE_CACHE=~/.cache/buildstream/sources
 
-To force rebuild session html while building the doc, simply build the docs like this::
+To force rebuild session html while building the doc, simply run `tox` with the
+``BST_FORCE_SESSION_REBUILD`` environment variable set, like so::
 
-  make BST_FORCE_SESSION_REBUILD=1 -C doc
+  env BST_FORCE_SESSION_REBUILD=1 tox -e docs
 
 
 Man pages
@@ -1478,6 +1465,8 @@ The elaborate documentation for pytest can be found here: http://doc.pytest.org/
 Don't get lost in the docs if you don't need to, follow existing examples instead.
 
 
+.. _contributing_build_deps:
+
 Installing build dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Some of BuildStream's dependencies have non-python build dependencies. When
diff --git a/tox.ini b/tox.ini
index 310fea229..955d95442 100644
--- a/tox.ini
+++ b/tox.ini
@@ -9,5 +9,25 @@ deps =
     -rtools/dev-requirements.txt
     -rtools/plugin-requirements.txt
 passenv =
+    BST_FORCE_BACKEND
     GI_TYPELIB_PATH
     INTEGRATION_CACHE
+
+[testenv:docs]
+commands =
+    make -C doc
+# Currently sphinx_rtd_theme does not support Sphinx >1.8, this breaks search functionality
+deps =
+    sphinx==1.7.9
+    sphinx-click
+    sphinx_rtd_theme
+    -rtools/requirements.txt
+    -rtools/plugin-requirements.txt
+passenv =
+    BST_FORCE_SESSION_REBUILD
+    BST_SOURCE_CACHE
+    HOME
+    LANG
+    LC_ALL
+whitelist_externals =
+    make