[Notes] [Git][BuildStream/buildstream][chandan/toxify] 2 commits: Move s

Chandan Singh pushed to branch chandan/toxify at BuildStream / buildstream

Commits:

3fae3446

by Chandan Singh at 2019-01-03T03:44:17Z

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`.

1f7bc655

by Chandan Singh at 2019-01-03T03:44:17Z

CONTRIBUTING.rst: Add instructions to recreate tox environment

When we update our dependencies, developers will eventually need to
recreate their `tox` environments to get correct results. This happens
because `tox` isn't particularly good at recognizing changes in the
requirements files.

3 changed files:

.gitlab-ci.yml
CONTRIBUTING.rst
tox.ini

Changes:

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

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

tox.ini

@@ -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

[Notes] [Git][BuildStream/buildstream][chandan/toxify] 2 commits: Move sphinx build functionality to tox

Chandan Singh pushed to branch chandan/toxify at BuildStream / buildstream

Commits:

3 changed files:

Changes: