Improvements to linting help sections.

 - Warn if help section is empty.
 - Warn if help section contains invalid RST.

Author: jmchilton

planemo_ext/galaxy/tools/linters/help.py

@@ -1,3 +1,4 @@
+from galaxy.util import rst_to_html
 
 
 def lint_help(tool_xml, lint_ctx):
@@ -11,5 +12,22 @@ def lint_help(tool_xml, lint_ctx):
         lint_ctx.warn("No help section found, consider adding a help section to your tool.")
         return
 
-    # TODO: validate help section RST.
+    help = helps[0].text
+    if not help.strip():
+        lint_ctx.warn("Help section appears to be empty.")
+        return
+
     lint_ctx.valid("Tool contains help section.")
+    invalid_rst = False
+    try:
+        rst_to_html(help)
+    except Exception as e:
+        invalid_rst = str(e)
+
+    if "TODO" in help:
+        lint_ctx.warn("Help contains TODO text.")
+
+    if invalid_rst:
+        lint_ctx.warn("Invalid reStructuredText found in help - [%s]." % invalid_rst)
+    else:
+        lint_ctx.valid("Help contains valid reStructuredText.")

planemo_ext/galaxy/util/__init__.py

@@ -10,13 +10,19 @@
     import grp
 except ImportError:
     grp = None
+try:
+    import docutils.core
+    import docutils.writers.html4css1
+except ImportError:
+    pass
 import errno
 import urlparse
 from tempfile import NamedTemporaryFile
-from logging import getLogger
-log = getLogger(__name__)
+import logging
+log = logging.getLogger(__name__)
 
 BUFFER_SIZE = 4096
+DEFAULT_ENCODING = os.environ.get('GALAXY_DEFAULT_ENCODING', 'utf-8')
 
 
 def enum(**enums):
@@ -130,6 +136,8 @@ def xml_text(root, name=None):
 # asbool implementation pulled from PasteDeploy
 truthy = frozenset(['true', 'yes', 'on', 'y', 't', '1'])
 falsy = frozenset(['false', 'no', 'off', 'n', 'f', '0'])
+
+
 def asbool(obj):
     if isinstance(obj, basestring):
         obj = obj.strip().lower()
@@ -193,3 +201,29 @@ def mask_password_from_url( url ):
             split._replace(netloc=split.netloc.replace("%s:%s" % (split.username, split.password), '%s:********' % split.username))
             url = urlparse.urlunsplit(split)
     return url
+
+
+def unicodify( value, encoding=DEFAULT_ENCODING, error='replace', default=None ):
+    """
+    Returns a unicode string or None
+    """
+
+    if isinstance( value, unicode ):
+        return value
+    try:
+        return unicode( str( value ), encoding, error )
+    except:
+        return default
+
+
+def rst_to_html( s ):
+    """Convert a blob of reStructuredText to HTML"""
+    log = logging.getLogger( "docutils" )
+
+    class FakeStream( object ):
+        def write( self, str ):
+            if len( str ) > 0 and not str.isspace():
+                log.warn( str )
+    return unicodify( docutils.core.publish_string( s,
+                      writer=docutils.writers.html4css1.Writer(),
+                      settings_overrides={ "embed_stylesheet": False, "template": os.path.join(os.path.dirname(__file__), "docutils_template.txt"), "warning_stream": FakeStream() } ) )

planemo_ext/galaxy/util/docutils_template.txt

@@ -0,0 +1 @@
+%(body)s

setup.py

@@ -18,6 +18,7 @@
     'six',
     'pyyaml',
     'jinja2',
+    'docutils',
 ]
 
 test_requirements = [
@@ -53,7 +54,9 @@
     ],
     data_files=[('tool_factory_2', ['tool_factory_2/rgToolFactory2.xml',
                                     'tool_factory_2/rgToolFactory2.py',
-                                    'tool_factory_2/getlocalrpackages.py'])],
+                                    'tool_factory_2/getlocalrpackages.py']),
+                ('planemo_ext/galaxy/util', ['planemo_ext/galaxy/util/docutils_template.txt']),
+               ],
     entry_points='''
         [console_scripts]
         planemo=planemo.cli:planemo