Permalink
Browse files

Documentation Linting

 - 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.
  • Loading branch information...
jmchilton committed Apr 21, 2016
1 parent 069e7ba commit a13a1206dd529c22ff3882de4c0d78dfaebca440
@@ -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
@@ -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

@@ -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.
No changes.
@@ -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
@@ -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
Binary file not shown.

This file was deleted.

Oops, something went wrong.
@@ -1,13 +1,6 @@
planemo.cwl package
===================

Subpackages
-----------

.. toctree::

planemo.cwl.cwl2script

Submodules
----------

This file was deleted.

Oops, something went wrong.
@@ -1,4 +1,5 @@
.. _shed:

=============================
Publishing to the Tool Shed
=============================
@@ -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
@@ -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()
10 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

0 comments on commit a13a120

Please sign in to comment.