/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
 12from __future__ import with_statement
 13
 14import os
 15import re
 16import sys
 17import getopt
 18import subprocess
 19from os.path import join, splitext, abspath, exists
 20from collections import defaultdict
 21
 22directives = [
 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
 44all_directives = '(' + '|'.join(directives) + ')'
 45seems_directive_re = re.compile(r'\.\. %s([^a-z:]|:(?!:))' % all_directives)
 46default_role_re = re.compile(r'(^| )`\w([^`]*?\w)?`($| )')
 47leaked_markup_re = re.compile(r'[a-z]::[^=]|:[a-z]+:|`|\.\.\s*\w+:')
 48
 49
 50checkers = {}
 51
 52checker_props = {'severity': 1, 'falsepositives': False}
 53
 54def 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)
 66def 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, err:
 76        yield err.lineno, 'not compilable: %s' % err
 77
 78
 79@checker('.rst', severity=2)
 80def 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')
 95def 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)
107def 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)
121def 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
130def main(argv):
131    usage = '''\
132Usage: %s [-v] [-f] [-s sev] [-i path]* [path]
133
134Options:  -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), 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 >>out, '[%d] %s:%d: %s' % (csev, fn, lno, msg)
216                        count[csev] += 1
217    if verbose:
218        print
219    if not count:
220        if severity > 1:
221            print 'No problems with severity >= %d found.' % severity
222        else:
223            print 'No problems found.'
224    else:
225        for severity in sorted(count):
226            number = count[severity]
227            print '%d problem%s with severity %d found.' % \
228                  (number, number > 1 and 's' or '', severity)
229    return int(bool(count))
230
231
232if __name__ == '__main__':
233    sys.exit(main(sys.argv))