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="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                 else:
  55                     last_comment = []
  56             if not comment:
  57                 l = line.strip()
  58                 m = re.search(r"pub\s+([A-Z_]+)", l)
  59
  60                 if m:
  61                     name = m.group(1).lower()
  62
  63                     while True:
  64                         m = re.search(level_re, line)
  65                         if m:
  66                             level = m.group(0)
  67                             break
  68
  69                         line = next(rs)
  70
  71                     print("found %s with level %s in %s" % (name, level, f))
  72                     d[name] = (level, last_comment)
  73                     last_comment = []
  74                     comment = True
  75                 if "}" in l:
  76                     print("Warning: Missing Lint-Name in", f)
  77                     comment = True
  78
  79 PREFIX = """Welcome to the rust-clippy wiki!
  80
  81 Here we aim to collect further explanations on the lints clippy provides. So \
  82 without further ado:
  83 """
  84
  85 WARNING = """
  86 # A word of warning
  87
  88 Clippy works as a *plugin* to the compiler, which means using an unstable \
  89 internal API. We have gotten quite good at keeping pace with the API \
  90 evolution, but the consequence is that clippy absolutely needs to be compiled \
  91 with the version of `rustc` it will run on, otherwise you will get strange \
  92 errors of missing symbols.
  93
  94 """
  95
  96
  97 template = """\n# `%s`
  98
  99 **Default level:** %s
 100
 101 %s"""
 102
 103 conf_template = """
 104 **Configuration:** This lint has the following configuration variables:
 105
 106 * `%s: %s`: %s (defaults to `%s`).
 107 """
 108
 109
 110 def write_wiki_page(d, c, f):
 111     keys = list(d.keys())
 112     keys.sort()
 113     with open(f, "w") as w:
 114         w.write(PREFIX)
 115
 116         for level in ('Deny', 'Warn', 'Allow'):
 117             w.write("\n**Those lints are %s by default**:\n\n" % level)
 118             for k in keys:
 119                 if d[k][0] == level:
 120                     w.write("[`%s`](#%s)\n" % (k, k))
 121
 122         w.write(WARNING)
 123         for k in keys:
 124             w.write(template % (k, d[k][0], "".join(d[k][1])))
 125
 126             if k in c:
 127                 w.write(conf_template % c[k])
 128
 129
 130 def check_wiki_page(d, c, f):
 131     errors = []
 132     with open(f) as w:
 133         for line in w:
 134             m = re.match("# `([a-z_]+)`", line)
 135             if m:
 136                 v = d.pop(m.group(1), "()")
 137                 if v == "()":
 138                     errors.append("Missing wiki entry: " + m.group(1))
 139     keys = list(d.keys())
 140     keys.sort()
 141     for k in keys:
 142         errors.append("Spurious wiki entry: " + k)
 143     if errors:
 144         print("\n".join(errors))
 145         sys.exit(1)
 146
 147
 148 def main():
 149     (d, c) = parse_path()
 150     if "-c" in sys.argv:
 151         check_wiki_page(d, c, "../rust-clippy.wiki/Home.md")
 152     else:
 153         write_wiki_page(d, c, "../rust-clippy.wiki/Home.md")
 154
 155 if __name__ == "__main__":
 156     main()