Documentation Linting

jmchilton · jmchilton · commit a13a1206dd52 · 2016-04-25T18:18:19.000-04:00
- Add Makefile target for linting docs.
 - Use RTD theme when building locally.
 - Fix linted doc issues.
 - Add tox target for linting docs.
 - Add TravisCI ENV for linting docs.
diff --git a/.travis.yml b/.travis.yml
@@ -5,6 +5,7 @@ env:
   - TOX_ENV=py27-lint
   - TOX_ENV=py34-lint
   - TOX_ENV=py27-lint-readme
+  - TOX_ENV=py27-lint-docs
   - TOX_ENV=py27
   - TOX_ENV=py34
   - TOX_ENV=py27-lint-imports
diff --git a/Makefile b/Makefile
@@ -11,6 +11,7 @@ IN_VENV=if [ -f $(VENV)/bin/activate ]; then . $(VENV)/bin/activate; fi;
 # TODO: add this upstream as a remote if it doesn't already exist.
 UPSTREAM?=galaxyproject
 SOURCE_DIR?=planemo
+SOURCE_DOC_EXCLUDE=$(SOURCE_DIR)/cwl/cwl2script
 BUILD_SCRIPTS_DIR=scripts
 VERSION?=$(shell python $(BUILD_SCRIPTS_DIR)/print_version_for_release.py $(SOURCE_DIR))
 DOC_URL?=https://planemo.readthedocs.org
@@ -79,13 +80,17 @@ ready-docs:
 	rm -f docs/$(SOURCE_DIR).rst
 	rm -f docs/planemo_ext.rst
 	rm -f docs/modules.rst
-	$(IN_VENV) sphinx-apidoc -f -o docs/ planemo_ext planemo_ext/galaxy/eggs
-	$(IN_VENV) sphinx-apidoc -f -o docs/ $(SOURCE_DIR)
+	$(IN_VENV) sphinx-apidoc -f -o docs/ planemo_ext
+	$(IN_VENV) sphinx-apidoc -f -o docs/ $(SOURCE_DIR) $(SOURCE_DOC_EXCLUDE)
 
 docs: ready-docs ## generate Sphinx HTML documentation, including API docs
 	$(IN_VENV) $(MAKE) -C docs clean
 	$(IN_VENV) $(MAKE) -C docs html
 
+lint-docs: ready-docs
+	$(IN_VENV) $(MAKE) -C docs clean
+	$(IN_VENV) $(MAKE) -C docs html 2>&1 | python $(BUILD_SCRIPTS_DIR)/lint_sphinx_output.py
+
 _open-docs:
 	open docs/_build/html/index.html || xdg-open docs/_build/html/index.html
 
diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -7,7 +7,9 @@ nose
 coverage
 
 #Building Docs
-sphinx
+sphinx==1.3.6
+# Sphinx bug with latest typing https://github.com/sphinx-doc/sphinx/issues/2470
+sphinx_rtd_theme
 recommonmark
 
 # Used to check readme.
diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep
diff --git a/docs/appliance.rst b/docs/appliance.rst
@@ -126,7 +126,7 @@ Launching the Appliance (Vagrant)
 ==================================
 
 The latest `Vagrant`_ version of the planemo appliance can be found
-`here <https://images.galaxyproject.org/planemo/latest.box>`_. Once you have
+`here <https://images.galaxyproject.org/planemo/latest.box>`__. Once you have
 installed `Vagrant`_ (`download now <http://www.vagrantup.com/downloads>`_),
 the appliance can be enabled by first creating a ``Vagrantfile`` in your tool
 directory - the following demonstrates an example of such file.
@@ -158,7 +158,7 @@ Together these make the OVA image ideal for learning such as for tutorials and
 workshops.
 
 The latest `VirtualBox`_ version of the planemo appliance can be found `here
-<https://images.galaxyproject.org/planemo/latest.ova>`_.
+<https://images.galaxyproject.org/planemo/latest.ova>`__.
 
 If VirtualBox_ has been installed - the planemo machine can be imported by
 downloading the latest image and double clicking the resulting file. This should
diff --git a/docs/conf.py b/docs/conf.py
@@ -32,6 +32,7 @@
 sys.path.insert(0, project_root)
 
 from recommonmark.parser import CommonMarkParser
+import sphinx_rtd_theme
 
 source_parsers = {
     '.md': CommonMarkParser,
@@ -117,7 +118,8 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the
diff --git a/docs/images/gx_toolbox_labels.png b/docs/images/gx_toolbox_labels.png
diff --git a/docs/planemo.cwl.cwl2script.rst b/docs/planemo.cwl.cwl2script.rst
diff --git a/docs/planemo.cwl.rst b/docs/planemo.cwl.rst
@@ -1,13 +1,6 @@
 planemo.cwl package
 ===================
 
-Subpackages
------------
-
-.. toctree::
-
-    planemo.cwl.cwl2script
-
 Submodules
 ----------
 
diff --git a/docs/planemo_ext.cwl2script.rst b/docs/planemo_ext.cwl2script.rst
diff --git a/docs/publishing.rst b/docs/publishing.rst
@@ -1,4 +1,5 @@
 .. _shed:
+
 =============================
 Publishing to the Tool Shed
 =============================
diff --git a/docs/writing_how_do_i.rst b/docs/writing_how_do_i.rst
@@ -254,9 +254,9 @@ description of the ``output``.
 
 - `metadata.xml <https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/metadata.xml>`__
 
-------------------------------------------------------
+--------------------------------------------------------------------
 \.\.\. test tools installed in an existing Galaxy instance?
-------------------------------------------------------
+--------------------------------------------------------------------
 
 Do not use planemo, Galaxy should be used to test its tools directly.
 The following two commands can be used to test Galaxy tools in an existing
diff --git a/scripts/lint_sphinx_output.py b/scripts/lint_sphinx_output.py
@@ -0,0 +1,31 @@
+from __future__ import print_function
+import sys
+import re
+
+IGNORE_PATTERNS = [
+    re.compile(r'nonlocal image URI found'),
+    re.compile(r'included in any toctree'),
+]
+
+
+def warning_line(line):
+    if 'WARNING' not in line:
+        return False
+    for pat in IGNORE_PATTERNS:
+        if pat.search(line):
+            return False
+    return True
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv
+    sphinx_output = sys.stdin.read()
+    warning_lines = filter(warning_line, sphinx_output.splitlines())
+    for line in warning_lines:
+        print(line)
+    sys.exit(1 if warning_lines else 0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tox.ini b/tox.ini
@@ -1,7 +1,7 @@
 # TODO: py34 to envlist
 # TODO: implement doc linting
 [tox]
-envlist = py34-lint, py27-lint, py27-lint-imports, py27-lint-docstrings, py27-lint-readme, py27
+envlist = py34-lint, py27-lint, py27-lint-imports, py27-lint-docstrings, py27-lint-readme, py27, py27-lint-docs
 source_dir = planemo
 test_dir = tests
 
@@ -44,3 +44,11 @@ skip_install = True
 whitelist_externals = make
 deps =
     readme
+
+[testenv:py27-lint-docs]
+commands = make lint-docs
+skip_install = True
+whitelist_externals = make
+deps =
+    -rrequirements.txt
+    -rdev-requirements.txt
