.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:

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
@@ -1552,6 +1541,12 @@ with::
 Alternatively, any IDE plugin that uses pytest should automatically
 detect the ``.pylintrc`` in the project's root directory.
 
+In case BuildStream's dependencies were updated since you last ran the
+tests, you might see some errors like
+``pytest: error: unrecognized arguments: --codestyle``. If this happens, you
+will need to force ``tox`` to recreate the test environment(s). To do so, you
+can run ``tox`` with ``-r`` or  ``--recreate`` option.
+
 .. note::
 
    By default, we do not allow use of site packages in our ``tox``

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