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