Mailing-List: contact commits-help@ariatosca.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@ariatosca.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: ran@apache.org
To: commits@ariatosca.incubator.apache.org
Date: Tue, 04 Jul 2017 13:51:38 -0000
Message-Id: <bc9e4a9f2b28466f8cbfc8a5521a573a@git.apache.org>
In-Reply-To: <f344d19226c5409ba8a701f17def0710@git.apache.org>
References: <f344d19226c5409ba8a701f17def0710@git.apache.org>
Subject: [2/2] incubator-ariatosca git commit: ARIA-287 Add tox environment
 for docs
archived-at: Tue, 04 Jul 2017 13:51:44 -0000

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/6c1f5801
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/6c1f5801
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/6c1f5801

Branch: refs/heads/ARIA-287-tox-for-docs
Commit: 6c1f580173923e2f34783bfba90300cc8803b4a5
Parents: ca808ae
Author: Tal Liron <tal.liron@gmail.com>
Authored: Fri Jun 30 17:08:23 2017 -0500
Committer: Ran Ziv <ran@gigaspaces.com>
Committed: Tue Jul 4 16:51:31 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/6c1f5801/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/6c1f5801/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/6c1f5801/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