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

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

.gitlab-ci.yml

+4 −11
Original line number Original line Diff line number Diff line
@@ -154,20 +154,13 @@ tests-fedora-missing-deps: 




# Automatically build documentation for every commit, we want to know

# Automatically build documentation for every commit, we want to know

# if building documentation fails even if we're not deploying it.

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

docs:

  stage: test

  stage: test

  variables:

    BST_FORCE_SESSION_REBUILD: 1

  script:

  script:

  - export BST_SOURCE_CACHE="$(pwd)/cache/integration-cache/sources"

  - env BST_SOURCE_CACHE="$(pwd)/cache/integration-cache/sources" tox -e docs

  # Currently sphinx_rtd_theme does not support Sphinx >1.8, this breaks search functionality

  - mv doc/build/html public

  - 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

  except:

  except:

  - schedules

  - schedules

  artifacts:

  artifacts:

CONTRIBUTING.rst

+9 −20
Original line number Original line Diff line number Diff line
@@ -1222,27 +1222,13 @@ For further information about using the reStructuredText with sphinx, please see 




Building Docs

Building Docs

~~~~~~~~~~~~~

~~~~~~~~~~~~~

The documentation build is not integrated into the ``setup.py`` and is

Before you can build the docs, you will end to ensure that you have installed

difficult (or impossible) to do so, so there is a little bit of setup

the required :ref:`buid dependencies <contributing_build_deps>` as mentioned

you need to take care of first.

in the testing section above.



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





To build the documentation, just run the following::

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

This will give you a ``doc/build/html`` directory with the html docs which

you can view in your browser locally to test.

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

  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

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.

Don't get lost in the docs if you don't need to, follow existing examples instead.









.. _contributing_build_deps:



Installing build dependencies

Installing build dependencies

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some of BuildStream's dependencies have non-python build dependencies. When

Some of BuildStream's dependencies have non-python build dependencies. When

tox.ini

+20 −0
Original line number Original line Diff line number Diff line
@@ -9,5 +9,25 @@ deps = 
    -rtools/dev-requirements.txt

    -rtools/dev-requirements.txt

    -rtools/plugin-requirements.txt

    -rtools/plugin-requirements.txt

passenv =

passenv =

    BST_FORCE_BACKEND

    GI_TYPELIB_PATH

    GI_TYPELIB_PATH

    INTEGRATION_CACHE

    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