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