1#!/usr/bin/env python3 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 12import os 13import re 14import sys 15import getopt 16from os.path import join, splitext, abspath, exists 17from collections import defaultdict 18 19directives = [ 20 # standard docutils ones 21 'admonition', 'attention', 'caution', 'class', 'compound', 'container', 22 'contents', 'csv-table', 'danger', 'date', 'default-role', 'epigraph', 23 'error', 'figure', 'footer', 'header', 'highlights', 'hint', 'image', 24 'important', 'include', 'line-block', 'list-table', 'meta', 'note', 25 'parsed-literal', 'pull-quote', 'raw', 'replace', 26 'restructuredtext-test-directive', 'role', 'rubric', 'sectnum', 'sidebar', 27 'table', 'target-notes', 'tip', 'title', 'topic', 'unicode', 'warning', 28 # Sphinx and Python docs custom ones 29 'acks', 'attribute', 'autoattribute', 'autoclass', 'autodata', 30 'autoexception', 'autofunction', 'automethod', 'automodule', 'centered', 31 'cfunction', 'class', 'classmethod', 'cmacro', 'cmdoption', 'cmember', 32 'code-block', 'confval', 'cssclass', 'ctype', 'currentmodule', 'cvar', 33 'data', 'decorator', 'decoratormethod', 'deprecated-removed', 34 'deprecated(?!-removed)', 'describe', 'directive', 'doctest', 'envvar', 35 'event', 'exception', 'function', 'glossary', 'highlight', 'highlightlang', 36 'impl-detail', 'index', 'literalinclude', 'method', 'miscnews', 'module', 37 'moduleauthor', 'opcode', 'pdbcommand', 'productionlist', 38 'program', 'role', 'sectionauthor', 'seealso', 'sourcecode', 'staticmethod', 39 'tabularcolumns', 'testcode', 'testoutput', 'testsetup', 'toctree', 'todo', 40 'todolist', 'versionadded', 'versionchanged' 41] 42 43all_directives = '(' + '|'.join(directives) + ')' 44seems_directive_re = re.compile(r'(?<!\.)\.\. %s([^a-z:]|:(?!:))' % all_directives) 45default_role_re = re.compile(r'(^| )`\w([^`]*?\w)?`($| )') 46leaked_markup_re = re.compile(r'[a-z]::\s|`|\.\.\s*\w+:') 47 48 49checkers = {} 50 51checker_props = {'severity': 1, 'falsepositives': False} 52 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 as 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.search(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 173 for root, dirs, files in os.walk(path): 174 # ignore subdirs in ignore list 175 if abspath(root) in ignore: 176 del dirs[:] 177 continue 178 179 for fn in files: 180 fn = join(root, fn) 181 if fn[:2] == './': 182 fn = fn[2:] 183 184 # ignore files in ignore list 185 if abspath(fn) in ignore: 186 continue 187 188 ext = splitext(fn)[1] 189 checkerlist = checkers.get(ext, None) 190 if not checkerlist: 191 continue 192 193 if verbose: 194 print('Checking %s...' % fn) 195 196 try: 197 with open(fn, 'r', encoding='utf-8') as f: 198 lines = list(f) 199 except (IOError, OSError) as err: 200 print('%s: cannot open: %s' % (fn, err)) 201 count[4] += 1 202 continue 203 204 for checker in checkerlist: 205 if checker.falsepositives and not falsepos: 206 continue 207 csev = checker.severity 208 if csev >= severity: 209 for lno, msg in checker(fn, lines): 210 print('[%d] %s:%d: %s' % (csev, fn, lno, msg)) 211 count[csev] += 1 212 if verbose: 213 print() 214 if not count: 215 if severity > 1: 216 print('No problems with severity >= %d found.' % severity) 217 else: 218 print('No problems found.') 219 else: 220 for severity in sorted(count): 221 number = count[severity] 222 print('%d problem%s with severity %d found.' % 223 (number, number > 1 and 's' or '', severity)) 224 return int(bool(count)) 225 226 227if __name__ == '__main__': 228 sys.exit(main(sys.argv)) 229