Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files
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.
  • Loading branch information
tliron authored and Ran Ziv committed Jul 4, 2017
1 parent cc1a230 commit 6c0842429bf2641f6cb74a355f9abebd0b8387f9
Showing 3 changed files with 54 additions and 16 deletions.
@@ -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
@@ -390,8 +390,20 @@
'__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 @@ def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
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)
28 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

0 comments on commit 6c08424

Please sign in to comment.