common/mangle-tmpl.py

   1 # -*- Mode: Python -*-
   2 # vi:si:et:sw=4:sts=4:ts=4
   3
   4 """
   5 use the output from gst-xmlinspect.py to mangle tmpl/*.sgml and
   6 insert/overwrite Short Description and Long Description
   7 """
   8
   9 # FIXME: right now it uses pygst and scans on its own;
  10 # we really should use inspect/*.xml instead since the result of
  11 # gst-xmlinspect.py is committed by the docs maintainer, who can be
  12 # expected to have pygst, but this step should be done for every docs build,
  13 # so no pygst allowed
  14
  15 # read in inspect/*.xml
  16 # for every tmpl/element-(name).xml: mangle with details from element
  17
  18 from __future__ import print_function, unicode_literals
  19
  20 import glob
  21 import re
  22 import sys
  23 import os
  24
  25 class Tmpl:
  26     def __init__(self, filename):
  27         self.filename = filename
  28         self._sectionids = []
  29         self._sections = {}
  30
  31     def read(self):
  32         """
  33         Read and parse the sections from the given file.
  34         """
  35         lines = open(self.filename).readlines()
  36         matcher = re.compile("<!-- ##### SECTION (\S+) ##### -->\n")
  37         id = None
  38
  39         for line in lines:
  40             match = matcher.search(line)
  41             if match:
  42                 id = match.expand("\\1")
  43                 self._sectionids.append(id)
  44                 self._sections[id] = []
  45             else:
  46                 if not id:
  47                     sys.stderr.write(
  48                         "WARNING: line before a SECTION header: %s" % line)
  49                 else:
  50                     self._sections[id].append(line)
  51
  52     def get_section(self, id):
  53         """
  54         Get the content from the given section.
  55         """
  56         return self._sections[id]
  57
  58     def set_section(self, id, content):
  59         """
  60         Replace the given section id with the given content.
  61         """
  62         self._sections[id] = content
  63
  64     def output(self):
  65         """
  66         Return the output of the current template in the tmpl/*.sgml format.
  67         """
  68         lines = []
  69         for id in self._sectionids:
  70             lines.append("<!-- ##### SECTION %s ##### -->\n" % id)
  71             for line in self._sections[id]:
  72                 lines.append(line)
  73
  74         return "".join(lines)
  75
  76     def write(self, backup=False):
  77         """
  78         Write out the template file again, backing up the previous one.
  79         """
  80         if backup:
  81             target = self.filename + ".mangle.bak"
  82             os.rename(self.filename, target)
  83
  84         handle = open(self.filename, "w")
  85         handle.write(self.output())
  86         handle.close()
  87
  88 import xml.dom.minidom
  89
  90 def get_elements(file):
  91     elements = {}
  92     doc = xml.dom.minidom.parse(file)
  93
  94     elem = None
  95     for e in doc.childNodes:
  96         if e.nodeType == e.ELEMENT_NODE and e.localName == 'plugin':
  97             elem = e
  98             break
  99     if elem == None:
 100         return None
 101
 102     elem2 = None
 103     for e in elem.childNodes:
 104         if e.nodeType == e.ELEMENT_NODE and e.localName == 'elements':
 105             elem2 = e
 106             break
 107     if elem2 == None:
 108         return None
 109
 110     elem = elem2
 111
 112     for e in elem.childNodes:
 113         if e.nodeType == e.ELEMENT_NODE and e.localName == 'element':
 114             name = None
 115             description = None
 116
 117             for e2 in e.childNodes:
 118                 if e2.nodeType == e2.ELEMENT_NODE and e2.localName == 'name':
 119                     name = e2.childNodes[0].nodeValue.encode("UTF-8")
 120                 elif e2.nodeType == e2.ELEMENT_NODE and e2.localName == 'description':
 121                     if e2.childNodes:
 122                       description = e2.childNodes[0].nodeValue.encode("UTF-8")
 123                     else:
 124                       description = 'No description'
 125
 126             if name != None and description != None:
 127                 elements[name] = {'description': description}
 128
 129     return elements
 130
 131 def main():
 132     if not len(sys.argv) == 3:
 133         sys.stderr.write('Please specify the inspect/ dir and the tmpl/ dir')
 134         sys.exit(1)
 135
 136     inspectdir = sys.argv[1]
 137     tmpldir = sys.argv[2]
 138
 139     # parse all .xml files; build map of element name -> short desc
 140     #for file in glob.glob("inspect/plugin-*.xml"):
 141     elements = {}
 142     for file in glob.glob("%s/plugin-*.xml" % inspectdir):
 143         elements.update(get_elements(file))
 144
 145     for file in glob.glob("%s/element-*.sgml" % tmpldir):
 146         base = os.path.basename(file)
 147         element = base[len("element-"):-len(".sgml")]
 148         tmpl = Tmpl(file)
 149         tmpl.read()
 150         if element in elements.keys():
 151             description = elements[element]['description']
 152             tmpl.set_section("Short_Description", "%s\n\n" % description)
 153
 154         # put in an include if not yet there
 155         line = '<include xmlns="http://www.w3.org/2003/XInclude" href="' + \
 156             'element-' + element + '-details.xml">' + \
 157             '<fallback xmlns="http://www.w3.org/2003/XInclude" />' + \
 158             '</include>\n'
 159         section = tmpl.get_section("Long_Description")
 160         if not section[0]  == line:
 161             section.insert(0, line)
 162         tmpl.set_section("Long_Description", section)
 163         tmpl.write()
 164
 165 main()