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
  13
  14 def parse_path(p="src"):
  15     d = {}
  16     for f in os.listdir(p):
  17         if f.endswith(".rs"):
  18             parse_file(d, os.path.join(p, f))
  19     return d
  20
  21 START = 0
  22 LINT = 1
  23
  24
  25 def parse_file(d, f):
  26     last_comment = []
  27     comment = True
  28
  29     with open(f) as rs:
  30         for line in rs:
  31             if comment:
  32                 if line.startswith("///"):
  33                     if line.startswith("/// "):
  34                         last_comment.append(line[4:])
  35                     else:
  36                         last_comment.append(line[3:])
  37                 elif line.startswith("declare_lint!"):
  38                     comment = False
  39                 else:
  40                     last_comment = []
  41             if not comment:
  42                 l = line.strip()
  43                 m = re.search(r"pub\s+([A-Z_]+)", l)
  44
  45                 if m:
  46                     name = m.group(1).lower()
  47
  48                     while True:
  49                         m = re.search(level_re, line)
  50                         if m:
  51                             level = m.group(0)
  52                             break
  53
  54                         line = next(rs)
  55
  56                     print("found %s with level %s in %s" % (name, level, f))
  57                     d[name] = (level, last_comment)
  58                     last_comment = []
  59                     comment = True
  60                 if "}" in l:
  61                     print("Warning: Missing Lint-Name in", f)
  62                     comment = True
  63
  64 PREFIX = """Welcome to the rust-clippy wiki!
  65
  66 Here we aim to collect further explanations on the lints clippy provides. So \
  67 without further ado:
  68 """
  69
  70 WARNING = """
  71 # A word of warning
  72
  73 Clippy works as a *plugin* to the compiler, which means using an unstable \
  74 internal API. We have gotten quite good at keeping pace with the API \
  75 evolution, but the consequence is that clippy absolutely needs to be compiled \
  76 with the version of `rustc` it will run on, otherwise you will get strange \
  77 errors of missing symbols.
  78
  79 """
  80
  81
  82 template = """# `%s`
  83
  84 **Default level:** %s
  85
  86 %s"""
  87
  88
  89 def write_wiki_page(d, f):
  90     keys = list(d.keys())
  91     keys.sort()
  92     with open(f, "w") as w:
  93         w.write(PREFIX)
  94
  95         for level in ('Deny', 'Warn', 'Allow'):
  96             w.write("\n**Those lints are %s by default**:\n\n" % level)
  97             for k in keys:
  98                 if d[k][0] == level:
  99                     w.write("[`%s`](#%s)\n" % (k, k))
 100
 101         w.write(WARNING)
 102         for k in keys:
 103             w.write(template % (k, d[k][0], "".join(d[k][1])))
 104
 105
 106 def check_wiki_page(d, f):
 107     errors = []
 108     with open(f) as w:
 109         for line in w:
 110             m = re.match("# `([a-z_]+)`", line)
 111             if m:
 112                 v = d.pop(m.group(1), "()")
 113                 if v == "()":
 114                     errors.append("Missing wiki entry: " + m.group(1))
 115     keys = list(d.keys())
 116     keys.sort()
 117     for k in keys:
 118         errors.append("Spurious wiki entry: " + k)
 119     if errors:
 120         print("\n".join(errors))
 121         sys.exit(1)
 122
 123
 124 def main():
 125     d = parse_path()
 126     if "-c" in sys.argv:
 127         check_wiki_page(d, "../rust-clippy.wiki/Home.md")
 128     else:
 129         write_wiki_page(d, "../rust-clippy.wiki/Home.md")
 130
 131 if __name__ == "__main__":
 132     main()