util/update_wiki.py

   1 #!/usr/bin/env python
   2 # Generate the wiki Home.md page from the contained doc comments
   3 # requires the checked out wiki in ../rust-clippy.wiki/
   4 # with -c option, print a warning and set exit status 1 if the file would be
   5 # changed.
   6 import os
   7 import re
   8 import sys
   9
  10
  11 level_re = re.compile(r'''(Forbid|Deny|Warn|Allow)''')
  12 conf_re = re.compile(r'''define_Conf! {\n([^}]*)\n}''', re.MULTILINE)
  13 confvar_re = re.compile(r'''/// Lint: (\w+). (.*).*\n *\("([^"]*)", (?:[^,]*), (.*) => (.*)\),''')
  14
  15
  16 def parse_path(p="clippy_lints/src"):
  17     d = {}
  18     for f in os.listdir(p):
  19         if f.endswith(".rs"):
  20             parse_file(d, os.path.join(p, f))
  21     return (d, parse_conf(p))
  22
  23
  24 def parse_conf(p):
  25     c = {}
  26     with open(p + '/utils/conf.rs') as f:
  27         f = f.read()
  28
  29         m = re.search(conf_re, f)
  30         m = m.groups()[0]
  31
  32         m = re.findall(confvar_re, m)
  33
  34         for (lint, doc, name, default, ty) in m:
  35             c[lint.lower()] = (name, ty, doc, default)
  36
  37     return c
  38
  39
  40 def parse_file(d, f):
  41     last_comment = []
  42     comment = True
  43
  44     with open(f) as rs:
  45         for line in rs:
  46             if comment:
  47                 if line.startswith("///"):
  48                     if line.startswith("/// "):
  49                         last_comment.append(line[4:])
  50                     else:
  51                         last_comment.append(line[3:])
  52                 elif line.startswith("declare_lint!"):
  53                     comment = False
  54                     deprecated = False
  55                     restriction = False
  56                 elif line.startswith("declare_restriction_lint!"):
  57                     comment = False
  58                     deprecated = False
  59                     restriction = True
  60                 elif line.startswith("declare_deprecated_lint!"):
  61                     comment = False
  62                     deprecated = True
  63                 else:
  64                     last_comment = []
  65             if not comment:
  66                 l = line.strip()
  67                 m = re.search(r"pub\s+([A-Z_][A-Z_0-9]*)", l)
  68
  69                 if m:
  70                     name = m.group(1).lower()
  71
  72                     # Intentionally either a never looping or infinite loop
  73                     while not deprecated and not restriction:
  74                         m = re.search(level_re, line)
  75                         if m:
  76                             level = m.group(0)
  77                             break
  78
  79                         line = next(rs)
  80
  81                     if deprecated:
  82                         level = "Deprecated"
  83                     elif restriction:
  84                         level = "Allow"
  85
  86                     print("found %s with level %s in %s" % (name, level, f))
  87                     d[name] = (level, last_comment)
  88                     last_comment = []
  89                     comment = True
  90                 if "}" in l:
  91                     print("Warning: Missing Lint-Name in", f)
  92                     comment = True
  93
  94 PREFIX = """Welcome to the rust-clippy wiki!
  95
  96 Here we aim to collect further explanations on the lints clippy provides. So \
  97 without further ado:
  98 """
  99
 100 WARNING = """
 101 # A word of warning
 102
 103 Clippy works as a *plugin* to the compiler, which means using an unstable \
 104 internal API. We have gotten quite good at keeping pace with the API \
 105 evolution, but the consequence is that clippy absolutely needs to be compiled \
 106 with the version of `rustc` it will run on, otherwise you will get strange \
 107 errors of missing symbols.
 108
 109 """
 110
 111
 112 template = """\n# `%s`
 113
 114 **Default level:** %s
 115
 116 %s"""
 117
 118 conf_template = """
 119 **Configuration:** This lint has the following configuration variables:
 120
 121 * `%s: %s`: %s (defaults to `%s`).
 122 """
 123
 124
 125 def level_message(level):
 126     if level == "Deprecated":
 127         return "\n**Those lints are deprecated**:\n\n"
 128     else:
 129         return "\n**Those lints are %s by default**:\n\n" % level
 130
 131
 132 def write_wiki_page(d, c, f):
 133     keys = list(d.keys())
 134     keys.sort()
 135     with open(f, "w") as w:
 136         w.write(PREFIX)
 137
 138         for level in ('Deny', 'Warn', 'Allow', 'Deprecated'):
 139             w.write(level_message(level))
 140             for k in keys:
 141                 if d[k][0] == level:
 142                     w.write("[`%s`](#%s)\n" % (k, k))
 143
 144         w.write(WARNING)
 145         for k in keys:
 146             w.write(template % (k, d[k][0], "".join(d[k][1])))
 147
 148             if k in c:
 149                 w.write(conf_template % c[k])
 150
 151
 152 def check_wiki_page(d, c, f):
 153     errors = []
 154     with open(f) as w:
 155         for line in w:
 156             m = re.match("# `([a-z_]+)`", line)
 157             if m:
 158                 v = d.pop(m.group(1), "()")
 159                 if v == "()":
 160                     errors.append("Missing wiki entry: " + m.group(1))
 161     keys = list(d.keys())
 162     keys.sort()
 163     for k in keys:
 164         errors.append("Spurious wiki entry: " + k)
 165     if errors:
 166         print("\n".join(errors))
 167         sys.exit(1)
 168
 169
 170 def main():
 171     (d, c) = parse_path()
 172     print('Found %s lints' % len(d))
 173     if "-c" in sys.argv:
 174         check_wiki_page(d, c, "../rust-clippy.wiki/Home.md")
 175     else:
 176         write_wiki_page(d, c, "../rust-clippy.wiki/Home.md")
 177
 178 if __name__ == "__main__":
 179     main()