Commit 3fae3446 authored by Chandan Singh's avatar Chandan Singh

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`.
parent afa0a369
......@@ -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:
......
......@@ -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
......
......@@ -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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment