diff options
| -rw-r--r-- | .gitlab-ci.yml | 15 | ||||
| -rw-r--r-- | CONTRIBUTING.rst | 29 | ||||
| -rw-r--r-- | tox.ini | 20 |
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 @@ -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 |