Doc/tools/rstlint.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3
   4 # Check for stylistic and formal issues in .rst and .py
   5 # files included in the documentation.
   6 #
   7 # 01/2009, Georg Brandl
   8
   9 # TODO: - wrong versions in versionadded/changed
  10 #       - wrong markup after versionchanged directive
  11
  12 from __future__ import with_statement
  13
  14 import os
  15 import re
  16 import sys
  17 import getopt
  18 import subprocess
  19 from os.path import join, splitext, abspath, exists
  20 from collections import defaultdict
  21
  22 directives = [
  23     # standard docutils ones
  24     'admonition', 'attention', 'caution', 'class', 'compound', 'container',
  25     'contents', 'csv-table', 'danger', 'date', 'default-role', 'epigraph',
  26     'error', 'figure', 'footer', 'header', 'highlights', 'hint', 'image',
  27     'important', 'include', 'line-block', 'list-table', 'meta', 'note',
  28     'parsed-literal', 'pull-quote', 'raw', 'replace',
  29     'restructuredtext-test-directive', 'role', 'rubric', 'sectnum', 'sidebar',
  30     'table', 'target-notes', 'tip', 'title', 'topic', 'unicode', 'warning',
  31     # Sphinx custom ones
  32     'acks', 'attribute', 'autoattribute', 'autoclass', 'autodata',
  33     'autoexception', 'autofunction', 'automethod', 'automodule', 'centered',
  34     'cfunction', 'class', 'classmethod', 'cmacro', 'cmdoption', 'cmember',
  35     'code-block', 'confval', 'cssclass', 'ctype', 'currentmodule', 'cvar',
  36     'data', 'deprecated', 'describe', 'directive', 'doctest', 'envvar', 'event',
  37     'exception', 'function', 'glossary', 'highlight', 'highlightlang', 'index',
  38     'literalinclude', 'method', 'module', 'moduleauthor', 'productionlist',
  39     'program', 'role', 'sectionauthor', 'seealso', 'sourcecode', 'staticmethod',
  40     'tabularcolumns', 'testcode', 'testoutput', 'testsetup', 'toctree', 'todo',
  41     'todolist', 'versionadded', 'versionchanged'
  42 ]
  43
  44 all_directives = '(' + '|'.join(directives) + ')'
  45 seems_directive_re = re.compile(r'\.\. %s([^a-z:]|:(?!:))' % all_directives)
  46 default_role_re = re.compile(r'(^| )`\w([^`]*?\w)?`($| )')
  47 leaked_markup_re = re.compile(r'[a-z]::[^=]|:[a-z]+:|`|\.\.\s*\w+:')
  48
  49
  50 checkers = {}
  51
  52 checker_props = {'severity': 1, 'falsepositives': False}
  53
  54 def checker(*suffixes, **kwds):
  55     """Decorator to register a function as a checker."""
  56     def deco(func):
  57         for suffix in suffixes:
  58             checkers.setdefault(suffix, []).append(func)
  59         for prop in checker_props:
  60             setattr(func, prop, kwds.get(prop, checker_props[prop]))
  61         return func
  62     return deco
  63
  64
  65 @checker('.py', severity=4)
  66 def check_syntax(fn, lines):
  67     """Check Python examples for valid syntax."""
  68     code = ''.join(lines)
  69     if '\r' in code:
  70         if os.name != 'nt':
  71             yield 0, '\\r in code file'
  72         code = code.replace('\r', '')
  73     try:
  74         compile(code, fn, 'exec')
  75     except SyntaxError as err:
  76         yield err.lineno, 'not compilable: %s' % err
  77
  78
  79 @checker('.rst', severity=2)
  80 def check_suspicious_constructs(fn, lines):
  81     """Check for suspicious reST constructs."""
  82     inprod = False
  83     for lno, line in enumerate(lines):
  84         if seems_directive_re.match(line):
  85             yield lno+1, 'comment seems to be intended as a directive'
  86         if '.. productionlist::' in line:
  87             inprod = True
  88         elif not inprod and default_role_re.search(line):
  89             yield lno+1, 'default role used'
  90         elif inprod and not line.strip():
  91             inprod = False
  92
  93
  94 @checker('.py', '.rst')
  95 def check_whitespace(fn, lines):
  96     """Check for whitespace and line length issues."""
  97     for lno, line in enumerate(lines):
  98         if '\r' in line:
  99             yield lno+1, '\\r in line'
 100         if '\t' in line:
 101             yield lno+1, 'OMG TABS!!!1'
 102         if line[:-1].rstrip(' \t') != line[:-1]:
 103             yield lno+1, 'trailing whitespace'
 104
 105
 106 @checker('.rst', severity=0)
 107 def check_line_length(fn, lines):
 108     """Check for line length; this checker is not run by default."""
 109     for lno, line in enumerate(lines):
 110         if len(line) > 81:
 111             # don't complain about tables, links and function signatures
 112             if line.lstrip()[0] not in '+|' and \
 113                'http://' not in line and \
 114                not line.lstrip().startswith(('.. function',
 115                                              '.. method',
 116                                              '.. cfunction')):
 117                 yield lno+1, "line too long"
 118
 119
 120 @checker('.html', severity=2, falsepositives=True)
 121 def check_leaked_markup(fn, lines):
 122     """Check HTML files for leaked reST markup; this only works if
 123     the HTML files have been built.
 124     """
 125     for lno, line in enumerate(lines):
 126         if leaked_markup_re.search(line):
 127             yield lno+1, 'possibly leaked markup: %r' % line
 128
 129
 130 def main(argv):
 131     usage = '''\
 132 Usage: %s [-v] [-f] [-s sev] [-i path]* [path]
 133
 134 Options:  -v       verbose (print all checked file names)
 135           -f       enable checkers that yield many false positives
 136           -s sev   only show problems with severity >= sev
 137           -i path  ignore subdir or file path
 138 ''' % argv[0]
 139     try:
 140         gopts, args = getopt.getopt(argv[1:], 'vfs:i:')
 141     except getopt.GetoptError:
 142         print(usage)
 143         return 2
 144
 145     verbose = False
 146     severity = 1
 147     ignore = []
 148     falsepos = False
 149     for opt, val in gopts:
 150         if opt == '-v':
 151             verbose = True
 152         elif opt == '-f':
 153             falsepos = True
 154         elif opt == '-s':
 155             severity = int(val)
 156         elif opt == '-i':
 157             ignore.append(abspath(val))
 158
 159     if len(args) == 0:
 160         path = '.'
 161     elif len(args) == 1:
 162         path = args[0]
 163     else:
 164         print(usage)
 165         return 2
 166
 167     if not exists(path):
 168         print('Error: path %s does not exist' % path)
 169         return 2
 170
 171     count = defaultdict(int)
 172     out = sys.stdout
 173
 174     for root, dirs, files in os.walk(path):
 175         # ignore subdirs controlled by svn
 176         if '.svn' in dirs:
 177             dirs.remove('.svn')
 178
 179         # ignore subdirs in ignore list
 180         if abspath(root) in ignore:
 181             del dirs[:]
 182             continue
 183
 184         for fn in files:
 185             fn = join(root, fn)
 186             if fn[:2] == './':
 187                 fn = fn[2:]
 188
 189             # ignore files in ignore list
 190             if abspath(fn) in ignore:
 191                 continue
 192
 193             ext = splitext(fn)[1]
 194             checkerlist = checkers.get(ext, None)
 195             if not checkerlist:
 196                 continue
 197
 198             if verbose:
 199                 print('Checking %s...' % fn)
 200
 201             try:
 202                 with open(fn, 'r') as f:
 203                     lines = list(f)
 204             except (IOError, OSError) as err:
 205                 print('%s: cannot open: %s' % (fn, err))
 206                 count[4] += 1
 207                 continue
 208
 209             for checker in checkerlist:
 210                 if checker.falsepositives and not falsepos:
 211                     continue
 212                 csev = checker.severity
 213                 if csev >= severity:
 214                     for lno, msg in checker(fn, lines):
 215                         print('[%d] %s:%d: %s' % (csev, fn, lno, msg),
 216                               file=out)
 217                         count[csev] += 1
 218     if verbose:
 219         print()
 220     if not count:
 221         if severity > 1:
 222             print('No problems with severity >= %d found.' % severity)
 223         else:
 224             print('No problems found.')
 225     else:
 226         for severity in sorted(count):
 227             number = count[severity]
 228             print('%d problem%s with severity %d found.' %
 229                   (number, number > 1 and 's' or '', severity))
 230     return int(bool(count))
 231
 232
 233 if __name__ == '__main__':
 234     sys.exit(main(sys.argv))