rstlint.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-

# Check for stylistic and formal issues in .rst and .py
# files included in the documentation.
#
# 01/2009, Georg Brandl

# TODO: - wrong versions in versionadded/changed
# - wrong markup after versionchanged directive

from __future__ importwith_statement

importos
importre
importsys
importgetopt
fromos.pathimportjoin, splitext, abspath, exists
fromcollectionsimportdefaultdict

directives= [
# standard docutils ones
'admonition', 'attention', 'caution', 'class', 'compound', 'container',
'contents', 'csv-table', 'danger', 'date', 'default-role', 'epigraph',
'error', 'figure', 'footer', 'header', 'highlights', 'hint', 'image',
'important', 'include', 'line-block', 'list-table', 'meta', 'note',
'parsed-literal', 'pull-quote', 'raw', 'replace',
'restructuredtext-test-directive', 'role', 'rubric', 'sectnum', 'sidebar',
'table', 'target-notes', 'tip', 'title', 'topic', 'unicode', 'warning',
# Sphinx and Python docs custom ones
'acks', 'attribute', 'autoattribute', 'autoclass', 'autodata',
'autoexception', 'autofunction', 'automethod', 'automodule', 'centered',
'cfunction', 'class', 'classmethod', 'cmacro', 'cmdoption', 'cmember',
'code-block', 'confval', 'cssclass', 'ctype', 'currentmodule', 'cvar',
'data', 'decorator', 'decoratormethod', 'deprecated-removed',
'deprecated(?!-removed)', 'describe', 'directive', 'doctest', 'envvar',
'event', 'exception', 'function', 'glossary', 'highlight', 'highlightlang',
'impl-detail', 'index', 'literalinclude', 'method', 'miscnews', 'module',
'moduleauthor', 'opcode', 'pdbcommand', 'productionlist',
'tabularcolumns', 'testcode', 'testoutput', 'testsetup', 'toctree', 'todo',
'todolist', 'versionadded', 'versionchanged'
]

all_directives='('+'|'.join(directives) +')'
seems_directive_re=re.compile(r'(?<!\.)\.\. %s([^a-z:]|:(?!:))'%all_directives)
default_role_re=re.compile(r'(^| )`\w([^`]*?\w)?`($| )')
leaked_markup_re=re.compile(r'[a-z]::\s|`|\.\.\s*\w+:')


checkers= {}

checker_props= {'severity': 1, 'falsepositives': False}

defchecker(*suffixes, **kwds):
"""Decorator to register a function as a checker."""
defdeco(func):
forsuffixinsuffixes:
checkers.setdefault(suffix, []).append(func)
forpropinchecker_props:
setattr(func, prop, kwds.get(prop, checker_props[prop]))
returnfunc
returndeco


@checker('.py', severity=4)
defcheck_syntax(fn, lines):
"""Check Python examples for valid syntax."""
code=''.join(lines)
if'\r'incode:
ifos.name!='nt':
yield0, '\\r in code file'
code=code.replace('\r', '')
try:
compile(code, fn, 'exec')
exceptSyntaxError, err:
yielderr.lineno, 'not compilable: %s'%err


@checker('.rst', severity=2)
defcheck_suspicious_constructs(fn, lines):
"""Check for suspicious reST constructs."""
inprod=False
forlno, lineinenumerate(lines):
ifseems_directive_re.search(line):
yieldlno+1, 'comment seems to be intended as a directive'
if'.. productionlist::'inline:
inprod=True
elifnotinprodanddefault_role_re.search(line):
yieldlno+1, 'default role used'
elifinprodandnotline.strip():
inprod=False


@checker('.py', '.rst')
defcheck_whitespace(fn, lines):
"""Check for whitespace and line length issues."""
forlno, lineinenumerate(lines):
if'\r'inline:
yieldlno+1, '\\r in line'
if'\t'inline:
yieldlno+1, 'OMG TABS!!!1'
ifline[:-1].rstrip(' \t') !=line[:-1]:
yieldlno+1, 'trailing whitespace'


@checker('.rst', severity=0)
defcheck_line_length(fn, lines):
"""Check for line length; this checker is not run by default."""
forlno, lineinenumerate(lines):
iflen(line) >81:
# don't complain about tables, links and function signatures
ifline.lstrip()[0] notin'+|'and \
'http://'notinlineand \
notline.lstrip().startswith(('.. function',
'.. method',
'.. cfunction')):
yieldlno+1, "line too long"


@checker('.html', severity=2, falsepositives=True)
defcheck_leaked_markup(fn, lines):
"""Check HTML files for leaked reST markup; this only works if
 the HTML files have been built.
 """
forlno, lineinenumerate(lines):
ifleaked_markup_re.search(line):
yieldlno+1, 'possibly leaked markup: %r'%line


defmain(argv):
usage='''\
Usage: %s [-v] [-f] [-s sev] [-i path]* [path]

Options: -v verbose (print all checked file names)
 -f enable checkers that yield many false positives
 -s sev only show problems with severity >= sev
 -i path ignore subdir or file path
'''%argv[0]
try:
gopts, args=getopt.getopt(argv[1:], 'vfs:i:')
exceptgetopt.GetoptError:
printusage
return2

verbose=False
severity=1
ignore= []
falsepos=False
foropt, valingopts:
ifopt=='-v':
verbose=True
elifopt=='-f':
falsepos=True
elifopt=='-s':
severity=int(val)
elifopt=='-i':
ignore.append(abspath(val))

iflen(args) ==0:
path='.'
eliflen(args) ==1:
path=args[0]
else:
printusage
return2

ifnotexists(path):
print'Error: path %s does not exist'%path
return2

count=defaultdict(int)
out=sys.stdout

forroot, dirs, filesinos.walk(path):
# ignore subdirs controlled by svn
if'.svn'indirs:
dirs.remove('.svn')

# ignore subdirs in ignore list
ifabspath(root) inignore:
deldirs[:]
continue

forfninfiles:
fn=join(root, fn)
iffn[:2] =='./':
fn=fn[2:]

# ignore files in ignore list
ifabspath(fn) inignore:
continue

ext=splitext(fn)[1]
checkerlist=checkers.get(ext, None)
ifnotcheckerlist:
continue

ifverbose:
print'Checking %s...'%fn

try:
withopen(fn, 'r') asf:
lines=list(f)
except (IOError, OSError), err:
print'%s: cannot open: %s'% (fn, err)
count[4] +=1
continue

forcheckerincheckerlist:
ifchecker.falsepositivesandnotfalsepos:
continue
csev=checker.severity
ifcsev>=severity:
forlno, msginchecker(fn, lines):
print>>out, '[%d] %s:%d: %s'% (csev, fn, lno, msg)
count[csev] +=1
ifverbose:
print
ifnotcount:
ifseverity>1:
print'No problems with severity >= %d found.'%severity
else:
print'No problems found.'
else:
forseverityinsorted(count):
number=count[severity]
print'%d problem%s with severity %d found.'% \
 (number, number>1and's'or'', severity)
returnint(bool(count))


if__name__=='__main__':
sys.exit(main(sys.argv))