ariatosca-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From emblempar...@apache.org
Subject [3/3] incubator-ariatosca git commit: ARIA-287 Add tox environment for docs
Date Mon, 03 Jul 2017 15:43:32 GMT
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/3ae8bbef
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/3ae8bbef
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/3ae8bbef

Branch: refs/heads/ARIA-287-tox-for-docs
Commit: 3ae8bbef0a11e9f2490f88b3533859c493186824
Parents: 3583f8c
Author: Tal Liron <tal.liron@gmail.com>
Authored: Fri Jun 30 17:08:23 2017 -0500
Committer: Tal Liron <tal.liron@gmail.com>
Committed: Mon Jul 3 10:43:21 2017 -0500

----------------------------------------------------------------------
 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/3ae8bbef/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/3ae8bbef/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/3ae8bbef/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


Mime
View raw message