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
   7 import re
   8 import sys
   9
  10 from lintlib import log, parse_all
  11
  12 PREFIX = """Welcome to the rust-clippy wiki!
  13
  14 Here we aim to collect further explanations on the lints clippy provides. So \
  15 without further ado:
  16 """
  17
  18 WARNING = """
  19 # A word of warning
  20
  21 Clippy works as a *plugin* to the compiler, which means using an unstable \
  22 internal API. We have gotten quite good at keeping pace with the API \
  23 evolution, but the consequence is that clippy absolutely needs to be compiled \
  24 with the version of `rustc` it will run on, otherwise you will get strange \
  25 errors of missing symbols.
  26
  27 """
  28
  29 TEMPLATE = """\n# `%s`
  30
  31 **Default level:** %s
  32
  33 %s"""
  34
  35 CONF_TEMPLATE = """
  36 **Configuration:** This lint has the following configuration variables:
  37
  38 * `%s: %s`: %s (defaults to `%s`).
  39 """
  40
  41
  42 def level_message(level):
  43     if level == "Deprecated":
  44         return "\n**Those lints are deprecated**:\n\n"
  45     else:
  46         return "\n**Those lints are %s by default**:\n\n" % level
  47
  48
  49 def write_wiki_page(lints, configs, filepath):
  50     lints.sort()
  51     with open(filepath, "w") as fp:
  52         fp.write(PREFIX)
  53
  54         for level in ('Deny', 'Warn', 'Allow', 'Deprecated'):
  55             fp.write(level_message(level))
  56             for lint in lints:
  57                 if lint.level == level:
  58                     fp.write("[`%s`](#%s)\n" % (lint.name, lint.name))
  59
  60         fp.write(WARNING)
  61         for lint in lints:
  62             fp.write(TEMPLATE % (lint.name, lint.level, "".join(lint.doc)))
  63
  64             if lint.name in configs:
  65                 fp.write(CONF_TEMPLATE % configs[lint.name])
  66
  67
  68 def check_wiki_page(lints, configs, filepath):
  69     lintdict = dict((lint.name, lint) for lint in lints)
  70     errors = False
  71     with open(filepath) as fp:
  72         for line in fp:
  73             m = re.match("# `([a-z_0-9]+)`", line)
  74             if m:
  75                 v = lintdict.pop(m.group(1), None)
  76                 if v is None:
  77                     log.error("Spurious wiki entry: %s", m.group(1))
  78                     errors = True
  79     for n in sorted(lintdict):
  80         log.error("Missing wiki entry: %s", n)
  81         errors = True
  82     if errors:
  83         return 1
  84
  85
  86 def main():
  87     lints, configs = parse_all()
  88     if "-c" in sys.argv:
  89         check_wiki_page(lints, configs, "../rust-clippy.wiki/Home.md")
  90     else:
  91         write_wiki_page(lints, configs, "../rust-clippy.wiki/Home.md")
  92
  93
  94 if __name__ == "__main__":
  95     main()