ARIA-287 Add tox environment for docs Also adds the environment to "make test". Involves fixing Sphinx to properly exclude SSH documentation when Fabric is not installed.
Project: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/commit/6c084242 Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/6c084242 Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/6c084242 Branch: refs/heads/ARIA-287-tox-for-docs Commit: 6c0842429bf2641f6cb74a355f9abebd0b8387f9 Parents: cc1a230 Author: Tal Liron <[email protected]> Authored: Fri Jun 30 17:08:23 2017 -0500 Committer: Ran Ziv <[email protected]> Committed: Tue Jul 4 17:18:45 2017 +0300 ---------------------------------------------------------------------- Makefile | 9 +++++++-- docs/conf.py | 33 +++++++++++++++++++++++++++++---- tox.ini | 28 ++++++++++++++++++---------- 3 files changed, 54 insertions(+), 16 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/6c084242/Makefile ---------------------------------------------------------------------- diff --git a/Makefile b/Makefile index 71a1968..a894747 100644 --- a/Makefile +++ b/Makefile @@ -47,11 +47,16 @@ install-virtual: docs: pip install --requirement "$(DOCS)/requirements.txt" rm -rf "$(HTML)" - sphinx-build -b html "$(DOCS)" "$(HTML)" + sphinx-build -W -T -b html "$(DOCS)" "$(HTML)" test: pip install --upgrade "tox>=2.7.0" - tox -e pylint_code -e pylint_tests -e py$(PYTHON_VERSION) -e py$(PYTHON_VERSION)e2e -e py$(PYTHON_VERSION)ssh + tox -e pylint_code \ + -e pylint_tests \ + -e py$(PYTHON_VERSION) \ + -e py$(PYTHON_VERSION)e2e \ + -e py$(PYTHON_VERSION)ssh \ + -e docs dist: docs python ./setup.py sdist bdist_wheel http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/6c084242/docs/conf.py ---------------------------------------------------------------------- diff --git a/docs/conf.py b/docs/conf.py index 6361621..fd1a066 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -390,8 +390,20 @@ NEVER_SKIP_MEMBERS = ( '__evaluate__', ) -# 'autodoc-skip-member' event -def on_skip_member(app, what, name, obj, skip, options): +SKIP_DOCUMENTS = () + +from sphinx import addnodes +from sphinx.domains.python import PythonDomain + +try: + import fabric +except: + # Note: "exclude_patterns" is not good enough for us, because we still have a TOC entry. + # Unfortunately, there is no way to conditionally exclude a TOC entry, and TOC entries without + # matching documents emit an error. So, we will have to manipulate the doctree directly! + SKIP_DOCUMENTS = ('aria.orchestrator.execution_plugin.ssh',) + +def on_autodoc_skip_member(app, what, name, obj, skip, options): if name in NEVER_SKIP_MEMBERS: return False if name in SKIP_MEMBERS: @@ -401,7 +413,18 @@ def on_skip_member(app, what, name, obj, skip, options): return True return skip -from sphinx.domains.python import PythonDomain +def on_source_read(app, docname, source): + # Empty out source + if docname in SKIP_DOCUMENTS: + source[0] = '' + +def on_doctree_read(app, doctree): + # Remove TOC entry (see: https://gist.github.com/kakawait/9215487) + for toctreenode in doctree.traverse(addnodes.toctree): + for e in toctreenode['entries']: + ref = str(e[1]) + if ref in SKIP_DOCUMENTS: + toctreenode['entries'].remove(e) class PatchedPythonDomain(PythonDomain): # See: https://github.com/sphinx-doc/sphinx/issues/3866 @@ -412,5 +435,7 @@ class PatchedPythonDomain(PythonDomain): env, fromdocname, builder, typ, target, node, contnode) def setup(app): - app.connect('autodoc-skip-member', on_skip_member) + app.connect('autodoc-skip-member', on_autodoc_skip_member) + app.connect('source-read', on_source_read) + app.connect('doctree-read', on_doctree_read) app.override_domain(PatchedPythonDomain) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/6c084242/tox.ini ---------------------------------------------------------------------- diff --git a/tox.ini b/tox.ini index 3e1fb3c..9849b5e 100644 --- a/tox.ini +++ b/tox.ini @@ -11,18 +11,19 @@ # limitations under the License. [tox] -envlist=py27,py26,py27e2e,py26e2e,pywin,py27ssh,pylint_code,pylint_tests +envlist=py27,py26,py27e2e,py26e2e,pywin,py27ssh,pylint_code,pylint_tests,docs [testenv] -passenv = - TRAVIS - PYTHON - PYTHON_VERSION - PYTHON_ARCH -deps = - -rrequirements.txt - -rtests/requirements.txt -basepython = +whitelist_externals=rm +passenv= + TRAVIS + PYTHON + PYTHON_VERSION + PYTHON_ARCH +deps= + -rrequirements.txt + -rtests/requirements.txt +basepython= py26: python2.6 py27: python2.7 py26e2e: python2.6 @@ -32,6 +33,7 @@ basepython = pywin: {env:PYTHON:}\python.exe pylint_code: python2.7 pylint_tests: python2.7 + docs: python2.7 [testenv:py27] commands=pytest tests --ignore=tests/end2end --ignore=tests/orchestrator/execution_plugin/test_ssh.py --cov-report term-missing --cov aria @@ -61,3 +63,9 @@ commands=pylint --rcfile=aria/.pylintrc --disable=fixme,missing-docstring aria e [testenv:pylint_tests] commands=pylint --rcfile=tests/.pylintrc --disable=fixme,missing-docstring tests + +[testenv:docs] +commands= + pip install --requirement docs/requirements.txt + rm --recursive --force docs/html + sphinx-build -W -T -b html docs docs/html
