tests/python/rst_to_doctree_mini.py

   1 # ##### BEGIN GPL LICENSE BLOCK #####
   2 #
   3 #  This program is free software; you can redistribute it and/or
   4 #  modify it under the terms of the GNU General Public License
   5 #  as published by the Free Software Foundation; either version 2
   6 #  of the License, or (at your option) any later version.
   7 #
   8 #  This program is distributed in the hope that it will be useful,
   9 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 #  GNU General Public License for more details.
  12 #
  13 #  You should have received a copy of the GNU General Public License
  14 #  along with this program; if not, write to the Free Software Foundation,
  15 #  Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16 #
  17 # ##### END GPL LICENSE BLOCK #####
  18
  19 # <pep8 compliant>
  20
  21 # Module with function to extract a doctree from an reStructuredText file.
  22 # Named 'Mini' because we only parse the minimum data needed to check
  23 # Python classes, methods and attributes match up to those in existing modules.
  24 # (To test for documentation completeness)
  25
  26 # note: literalinclude's are not followed.
  27 # could be nice to add but not really needed either right now.
  28
  29 import collections
  30
  31 Directive = collections.namedtuple(
  32     "Directive",
  33     ("type",
  34      "value",
  35      "value_strip",
  36      "line",
  37      "indent",
  38      "members"))
  39
  40
  41 def parse_rst_py(filepath):
  42     import re
  43
  44     # Get the prefix assuming the line is lstrip()'d
  45     # ..foo:: bar
  46     # -->
  47     # ("foo", "bar")
  48     re_prefix = re.compile(r"^\.\.\s([a-zA-Z09\-]+)::\s*(.*)\s*$")
  49
  50     tree = collections.defaultdict(list)
  51     indent_map = {}
  52     indent_prev = 0
  53     f = open(filepath, encoding="utf-8")
  54     for i, line in enumerate(f):
  55         line_strip = line.lstrip()
  56         # ^\.\.\s[a-zA-Z09\-]+::.*$
  57         # if line.startswith(".. "):
  58         march = re_prefix.match(line_strip)
  59
  60         if march:
  61             directive, value = march.group(1, 2)
  62             indent = len(line) - len(line_strip)
  63             value_strip = value.replace("(", " ").split()
  64             value_strip = value_strip[0] if value_strip else ""
  65
  66             item = Directive(type=directive,
  67                              value=value,
  68                              value_strip=value_strip,
  69                              line=i,
  70                              indent=indent,
  71                              members=[])
  72
  73             tree[indent].append(item)
  74             if indent_prev < indent:
  75                 indent_map[indent] = indent_prev
  76             if indent > 0:
  77                 tree[indent_map[indent]][-1].members.append(item)
  78             indent_prev = indent
  79     f.close()
  80
  81     return tree[0]
  82
  83
  84 def main():
  85     # not intended use, but may as well print rst files passed as a test.
  86     import sys
  87     for arg in sys.argv:
  88         if arg.lower().endswith((".txt", ".rst")):
  89             items = parse_rst_py(arg)
  90             for i in items:
  91                 print(i)
  92
  93
  94 if __name__ == "__main__":
  95     main()