ariatosca-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From emblempar...@apache.org
Subject incubator-ariatosca git commit: ARIA-287 Add tox environment for docs
Date Fri, 30 Jun 2017 22:10:06 GMT
Repository: incubator-ariatosca
Updated Branches:
  refs/heads/ARIA-287-tox-for-docs [created] ee43a3c46


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

Branch: refs/heads/ARIA-287-tox-for-docs
Commit: ee43a3c469e21880eacaf848a1ac7080d46e17a0
Parents: 2ed2e1c
Author: Tal Liron <tal.liron@gmail.com>
Authored: Fri Jun 30 17:08:23 2017 -0500
Committer: Tal Liron <tal.liron@gmail.com>
Committed: Fri Jun 30 17:08:23 2017 -0500

----------------------------------------------------------------------
 Makefile     |  9 +++++++--
 docs/conf.py | 33 +++++++++++++++++++++++++++++----
 tox.ini      | 15 +++++++++++----
 3 files changed, 47 insertions(+), 10 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/ee43a3c4/Makefile
----------------------------------------------------------------------
diff --git a/Makefile b/Makefile
index 50675bf..88b18b9 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/ee43a3c4/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/ee43a3c4/tox.ini
----------------------------------------------------------------------
diff --git a/tox.ini b/tox.ini
index 3e1fb3c..5f10eae 100644
--- a/tox.ini
+++ b/tox.ini
@@ -11,18 +11,20 @@
 # 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 =
+whitelist_externals=rm
+passenv=
     TRAVIS
     PYTHON
     PYTHON_VERSION
     PYTHON_ARCH
-deps =
+deps=
     -rrequirements.txt
     -rtests/requirements.txt
-basepython =
+    -rdocs/requirements.txt
+basepython=
   py26: python2.6
   py27: python2.7
   py26e2e: python2.6
@@ -32,6 +34,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 +64,7 @@ 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=rm -rf docs/html
+  sphinx-build -W -T -b html docs docs/html


Mime
View raw message