doc/tools/undoc_symbols.py

   1 #! /usr/bin/env python
   2
   3 """\
   4 This script prints out a list of undocumented symbols found in
   5 Python include files, prefixed by their tag kind.
   6
   7 Pass Python's include files to ctags, parse the output into a
   8 dictionary mapping symbol names to tag kinds.
   9
  10 Then, the .tex files from Python docs are read into a giant string.
  11
  12 Finally all symbols not found in the docs are written to standard
  13 output, prefixed with their tag kind.
  14 """
  15
  16 # Which kind of tags do we need?
  17 TAG_KINDS = "dpst"
  18
  19 # Doc sections to use
  20 DOCSECTIONS = ["api"]# ["api", "ext"]
  21
  22 # Only print symbols starting with this prefix,
  23 # to get all symbols, use an empty string
  24 PREFIXES = ("Py", "PY")
  25
  26 INCLUDEPATTERN = "*.h"
  27
  28 # end of customization section
  29
  30
  31 # Tested with EXUBERANT CTAGS
  32 # see http://ctags.sourceforge.net
  33 #
  34 # ctags fields are separated by tabs.
  35 # The first field is the name, the last field the type:
  36 # d macro definitions (and #undef names)
  37 # e enumerators
  38 # f function definitions
  39 # g enumeration names
  40 # m class, struct, or union members
  41 # n namespaces
  42 # p function prototypes and declarations
  43 # s structure names
  44 # t typedefs
  45 # u union names
  46 # v variable definitions
  47 # x extern and forward variable declarations
  48
  49 import os, glob, re, sys
  50
  51 def findnames(file, prefixes=()):
  52     names = {}
  53     for line in file.xreadlines():
  54         if line[0] == '!':
  55             continue
  56         fields = line.split()
  57         name, tag = fields[0], fields[-1]
  58         if tag == 'd' and name.endswith('_H'):
  59             continue
  60         if prefixes:
  61             sw = name.startswith
  62             for prefix in prefixes:
  63                 if sw(prefix):
  64                     names[name] = tag
  65         else:
  66             names[name] = tag
  67     return names
  68
  69 def print_undoc_symbols(prefix, docdir, incdir):
  70     docs = []
  71
  72     for sect in DOCSECTIONS:
  73         for file in glob.glob(os.path.join(docdir, sect, "*.tex")):
  74             docs.append(open(file).read())
  75
  76     docs = "\n".join(docs)
  77
  78     incfiles = os.path.join(incdir, INCLUDEPATTERN)
  79
  80     fp = os.popen("ctags -IPyAPI_FUNC -IPy_GCC_ATTRIBUTE --c-types=%s -f - %s"
  81                   % (TAG_KINDS, incfiles))
  82     dict = findnames(fp, prefix)
  83     names = dict.keys()
  84     names.sort()
  85     for name in names:
  86         if not re.search("%s\\W" % name, docs):
  87             print dict[name], name
  88
  89 if __name__ == '__main__':
  90     srcdir = os.path.dirname(sys.argv[0])
  91     incdir = os.path.normpath(os.path.join(srcdir, "../../Include"))
  92     docdir = os.path.normpath(os.path.join(srcdir, ".."))
  93
  94     print_undoc_symbols(PREFIXES, docdir, incdir)