Chandan Singh pushed to branch chandan/toxify at BuildStream / buildstream
Commits:
-
7f292a78
by Chandan Singh at 2018-12-31T09:50:37Z
3 changed files:
Changes:
| ... | ... | @@ -158,20 +158,18 @@ tests-fedora-missing-deps: |
| 158 | 158 |
|
| 159 | 159 |
# Automatically build documentation for every commit, we want to know
|
| 160 | 160 |
# if building documentation fails even if we're not deploying it.
|
| 161 |
-# Note: We still do not enforce a consistent installation of python3-sphinx,
|
|
| 162 |
-# as it will significantly grow the backing image.
|
|
| 163 | 161 |
docs:
|
| 164 | 162 |
stage: test
|
| 163 |
+ variables:
|
|
| 164 |
+ BST_FORCE_SESSION_REBUILD: 1
|
|
| 165 |
+ before_script:
|
|
| 166 |
+ # FIXME: this deps should ideally be provided by the testsuite images
|
|
| 167 |
+ - pip3 install tox
|
|
| 168 |
+ - |
|
|
| 169 |
+ bash -c '( apt-get update && apt-get install -y python3-dev gcc libcairo2-dev pkg-config libgirepository1.0-dev ) || ( dnf install -y gcc python3-devel gobject-introspection-devel glib2-devel cairo-gobject-devel )'
|
|
| 165 | 170 |
script:
|
| 166 |
- - export BST_SOURCE_CACHE="$(pwd)/cache/integration-cache/sources"
|
|
| 167 |
- # Currently sphinx_rtd_theme does not support Sphinx >1.8, this breaks search functionality
|
|
| 168 |
- - pip3 install sphinx==1.7.9
|
|
| 169 |
- - pip3 install sphinx-click
|
|
| 170 |
- - pip3 install sphinx_rtd_theme
|
|
| 171 |
- - cd dist && ./unpack.sh && cd buildstream
|
|
| 172 |
- - make BST_FORCE_SESSION_REBUILD=1 -C doc
|
|
| 173 |
- - cd ../..
|
|
| 174 |
- - mv dist/buildstream/doc/build/html public
|
|
| 171 |
+ - env BST_SOURCE_CACHE="$(pwd)/cache/integration-cache/sources" tox -e docs
|
|
| 172 |
+ - mv doc/build/html public
|
|
| 175 | 173 |
except:
|
| 176 | 174 |
- schedules
|
| 177 | 175 |
artifacts:
|
| ... | ... | @@ -1222,27 +1222,13 @@ For further information about using the reStructuredText with sphinx, please see |
| 1222 | 1222 |
|
| 1223 | 1223 |
Building Docs
|
| 1224 | 1224 |
~~~~~~~~~~~~~
|
| 1225 |
-The documentation build is not integrated into the ``setup.py`` and is
|
|
| 1226 |
-difficult (or impossible) to do so, so there is a little bit of setup
|
|
| 1227 |
-you need to take care of first.
|
|
| 1228 |
- |
|
| 1229 |
-Before you can build the BuildStream documentation yourself, you need
|
|
| 1230 |
-to first install ``sphinx`` along with some additional plugins and dependencies,
|
|
| 1231 |
-using pip or some other mechanism::
|
|
| 1232 |
- |
|
| 1233 |
- # Install sphinx
|
|
| 1234 |
- pip3 install --user sphinx
|
|
| 1235 |
- |
|
| 1236 |
- # Install some sphinx extensions
|
|
| 1237 |
- pip3 install --user sphinx-click
|
|
| 1238 |
- pip3 install --user sphinx_rtd_theme
|
|
| 1239 |
- |
|
| 1240 |
- # Additional optional dependencies required
|
|
| 1241 |
- pip3 install --user arpy
|
|
| 1225 |
+Before you can build the docs, you will end to ensure that you have installed
|
|
| 1226 |
+the required :ref:`buid dependencies <contributing_build_deps>` as mentioned
|
|
| 1227 |
+in the testing section above.
|
|
| 1242 | 1228 |
|
| 1243 | 1229 |
To build the documentation, just run the following::
|
| 1244 | 1230 |
|
| 1245 |
- make -C doc
|
|
| 1231 |
+ tox -e docs
|
|
| 1246 | 1232 |
|
| 1247 | 1233 |
This will give you a ``doc/build/html`` directory with the html docs which
|
| 1248 | 1234 |
you can view in your browser locally to test.
|
| ... | ... | @@ -1260,9 +1246,10 @@ will make the docs build reuse already downloaded sources:: |
| 1260 | 1246 |
|
| 1261 | 1247 |
export BST_SOURCE_CACHE=~/.cache/buildstream/sources
|
| 1262 | 1248 |
|
| 1263 |
-To force rebuild session html while building the doc, simply build the docs like this::
|
|
| 1249 |
+To force rebuild session html while building the doc, simply run `tox` with the
|
|
| 1250 |
+``BST_FORCE_SESSION_REBUILD`` environment variable set, like so::
|
|
| 1264 | 1251 |
|
| 1265 |
- make BST_FORCE_SESSION_REBUILD=1 -C doc
|
|
| 1252 |
+ env BST_FORCE_SESSION_REBUILD=1 tox -e docs
|
|
| 1266 | 1253 |
|
| 1267 | 1254 |
|
| 1268 | 1255 |
Man pages
|
| ... | ... | @@ -1478,6 +1465,8 @@ The elaborate documentation for pytest can be found here: http://doc.pytest.org/ |
| 1478 | 1465 |
Don't get lost in the docs if you don't need to, follow existing examples instead.
|
| 1479 | 1466 |
|
| 1480 | 1467 |
|
| 1468 |
+.. _contributing_build_deps:
|
|
| 1469 |
+ |
|
| 1481 | 1470 |
Installing build dependencies
|
| 1482 | 1471 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 1483 | 1472 |
Some of BuildStream's dependencies have non-python build dependencies. When
|
| ... | ... | @@ -10,3 +10,18 @@ deps = |
| 10 | 10 |
-rtools/plugin-requirements.txt
|
| 11 | 11 |
passenv =
|
| 12 | 12 |
GI_TYPELIB_PATH
|
| 13 |
+ BST_FORCE_BACKEND
|
|
| 14 |
+ |
|
| 15 |
+[testenv:docs]
|
|
| 16 |
+commands=
|
|
| 17 |
+ make -C doc
|
|
| 18 |
+# Currently sphinx_rtd_theme does not support Sphinx >1.8, this breaks search functionality
|
|
| 19 |
+deps =
|
|
| 20 |
+ sphinx==1.7.9
|
|
| 21 |
+ sphinx-click
|
|
| 22 |
+ sphinx_rtd_theme
|
|
| 23 |
+ -rtools/requirements.txt
|
|
| 24 |
+ -rtools/plugin-requirements.txt
|
|
| 25 |
+passenv =
|
|
| 26 |
+ BST_SOURCE_CACHE
|
|
| 27 |
+ BST_FORCE_SESSION_REBUILD
|