text: #!/usr/bin/env python3
  # -*- 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
  
  import os
  import re
  import sys
  import getopt
  from os.path import join, splitext, abspath, exists
  from collections import defaultdict
  
  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',
      'availability', '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', 'program', 'role', 'sectionauthor', 'seealso',
      'sourcecode', 'staticmethod', '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}
  
  
  def checker(*suffixes, **kwds):
      """Decorator to register a function as a checker."""
      def deco(func):
          for suffix in suffixes:
              checkers.setdefault(suffix, []).append(func)
          for prop in checker_props:
              setattr(func, prop, kwds.get(prop, checker_props[prop]))
          return func
      return deco
  
  
  @checker('.py', severity=4)
  def check_syntax(fn, lines):
      """Check Python examples for valid syntax."""
      code = ''.join(lines)
      if '\r' in code:
          if os.name != 'nt':
              yield 0, '\\r in code file'
          code = code.replace('\r', '')
      try:
          compile(code, fn, 'exec')
      except SyntaxError as err:
          yield err.lineno, 'not compilable: %s' % err
  
  
  @checker('.rst', severity=2)
  def check_suspicious_constructs(fn, lines):
      """Check for suspicious reST constructs."""
      inprod = False
      for lno, line in enumerate(lines):
          if seems_directive_re.search(line):
              yield lno+1, 'comment seems to be intended as a directive'
          if '.. productionlist::' in line:
              inprod = True
          elif not inprod and default_role_re.search(line):
              yield lno+1, 'default role used'
          elif inprod and not line.strip():
              inprod = False
  
  
  @checker('.py', '.rst')
  def check_whitespace(fn, lines):
      """Check for whitespace and line length issues."""
      for lno, line in enumerate(lines):
          if '\r' in line:
              yield lno+1, '\\r in line'
          if '\t' in line:
              yield lno+1, 'OMG TABS!!!1'
          if line[:-1].rstrip(' \t') != line[:-1]:
              yield lno+1, 'trailing whitespace'
  
  
  @checker('.rst', severity=0)
  def check_line_length(fn, lines):
      """Check for line length; this checker is not run by default."""
      for lno, line in enumerate(lines):
          if len(line) > 81:
              # don't complain about tables, links and function signatures
              if line.lstrip()[0] not in '+|' and \
                 'http://' not in line and \
                 not line.lstrip().startswith(('.. function',
                                               '.. method',
                                               '.. cfunction')):
                  yield lno+1, "line too long"
  
  
  @checker('.html', severity=2, falsepositives=True)
  def check_leaked_markup(fn, lines):
      """Check HTML files for leaked reST markup; this only works if
      the HTML files have been built.
      """
      for lno, line in enumerate(lines):
          if leaked_markup_re.search(line):
              yield lno+1, 'possibly leaked markup: %r' % line
  
  
  def main(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:')
      except getopt.GetoptError:
          print(usage)
          return 2
  
      verbose = False
      severity = 1
      ignore = []
      falsepos = False
      for opt, val in gopts:
          if opt == '-v':
              verbose = True
          elif opt == '-f':
              falsepos = True
          elif opt == '-s':
              severity = int(val)
          elif opt == '-i':
              ignore.append(abspath(val))
  
      if len(args) == 0:
          path = '.'
      elif len(args) == 1:
          path = args[0]
      else:
          print(usage)
          return 2
  
      if not exists(path):
          print('Error: path %s does not exist' % path)
          return 2
  
      count = defaultdict(int)
  
      for root, dirs, files in os.walk(path):
          # ignore subdirs in ignore list
          if abspath(root) in ignore:
              del dirs[:]
              continue
  
          for fn in files:
              fn = join(root, fn)
              if fn[:2] == './':
                  fn = fn[2:]
  
              # ignore files in ignore list
              if abspath(fn) in ignore:
                  continue
  
              ext = splitext(fn)[1]
              checkerlist = checkers.get(ext, None)
              if not checkerlist:
                  continue
  
              if verbose:
                  print('Checking %s...' % fn)
  
              try:
                  with open(fn, 'r', encoding='utf-8') as f:
                      lines = list(f)
              except (IOError, OSError) as err:
                  print('%s: cannot open: %s' % (fn, err))
                  count[4] += 1
                  continue
  
              for checker in checkerlist:
                  if checker.falsepositives and not falsepos:
                      continue
                  csev = checker.severity
                  if csev >= severity:
                      for lno, msg in checker(fn, lines):
                          print('[%d] %s:%d: %s' % (csev, fn, lno, msg))
                          count[csev] += 1
      if verbose:
          print()
      if not count:
          if severity > 1:
              print('No problems with severity >= %d found.' % severity)
          else:
              print('No problems found.')
      else:
          for severity in sorted(count):
              number = count[severity]
              print('%d problem%s with severity %d found.' %
                    (number, number > 1 and 's' or '', severity))
      return int(bool(count))
  
  
  if __name__ == '__main__':
      sys.exit(main(sys.argv))
  