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