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