[NaCl SDK Docs] Simplify PPAPI documentation generation.

native_client_sdk/src/doc/doxygen/doxy_cleanup.py

 #!/usr/bin/python
 
 # Copyright (c) 2011 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 '''This utility cleans up the html files as emitted by doxygen so
 that they are suitable for publication on a Google documentation site.
 '''
 
+import glob
 import optparse
 import os
 import re
 import shutil
-import string
 import sys
 try:
   from BeautifulSoup import BeautifulSoup, Tag
 except (ImportError, NotImplementedError):
   print ("This tool requires the BeautifulSoup package "
          "(see http://www.crummy.com/software/BeautifulSoup/).\n"
          "Make sure that the file BeautifulSoup.py is either in this directory "
          "or is available in your PYTHON_PATH")
   raise
 
 
+def Trace(msg):
+  if Trace.verbose:
+    sys.stderr.write(str(msg) + '\n')
+
+Trace.verbose = False
+
+
+FILES_TO_REMOVE = [
+  '*.css',
+  '*.map',
+  '*.md5',
+  'annotated.html',
+  'bc_s.png',
+  'classes.html',
+  'closed.png',
+  'doxygen.png',
+  'files.html',
+  'functions*.html',
+  'globals_0x*.html',
+  'globals_enum.html',
+  'globals_eval.html',
+  'globals_func.html',
+  'globals.html',
+  'globals_type.html',
+  'globals_vars.html',
+  'graph_legend.html',
+  'graph_legend.png',
+  'hierarchy.html',
+  'index_8dox.html',
+  'index.html',
+  'modules.html',
+  'namespacemembers_func.html',
+  'namespacemembers.html',
+  'namespaces.html',
+  'nav_f.png',
+  'nav_h.png',
+  'open.png',
+  'tab_a.png',
+  'tab_b.png',
+  'tab_h.png',
+  'tab_s.png',
+]
+
+
 class HTMLFixer(object):
   '''This class cleans up the html strings as produced by Doxygen
   '''
 
   def __init__(self, html):
     self.soup = BeautifulSoup(html)
 
   def FixTableHeadings(self):
     '''Fixes the doxygen table headings.
 
@@ skipping 22 matching lines @@
       if tag.td and tag.td.h2 and tag.td.h2.a and tag.td.h2.a['name']:
         #tag['id'] = tag.td.h2.a['name']
         tag.string = tag.td.h2.a.next
         tag.name = 'h2'
         table_headers.append(tag)
 
     # reverse the list so that earlier tags don't delete later tags
     table_headers.reverse()
     # Split up tables that have multiple table header (th) rows
     for tag in table_headers:
-      print "Header tag: %s is %s" % (tag.name, tag.string.strip())
+      Trace("Header tag: %s is %s" % (tag.name, tag.string.strip()))
       # Is this a heading in the middle of a table?
       if tag.findPreviousSibling('tr') and tag.parent.name == 'table':
-        print "Splitting Table named %s" % tag.string.strip()
+        Trace("Splitting Table named %s" % tag.string.strip())
         table = tag.parent
         table_parent = table.parent
         table_index = table_parent.contents.index(table)
         new_table = Tag(self.soup, name='table', attrs=table.attrs)
         table_parent.insert(table_index + 1, new_table)
         tag_index = table.contents.index(tag)
         for index, row in enumerate(table.contents[tag_index:]):
           new_table.insert(index, row)
       # Now move the <h2> tag to be in front of the <table> tag
       assert tag.parent.name == 'table'
       table = tag.parent
       table_parent = table.parent
       table_index = table_parent.contents.index(table)
       table_parent.insert(table_index, tag)
 
   def RemoveTopHeadings(self):
     '''Removes <div> sections with a header, tabs, or navpath class attribute'''
     header_tags = self.soup.findAll(
         name='div',
         attrs={'class' : re.compile('^(header|tabs[0-9]*|navpath)$')})
     [tag.extract() for tag in header_tags]
 
+  def RemoveVersionNumbers(self, html):
+    '''Horrible hack to strip _#_# from struct names.'''
+    return re.sub(r'(_\d_\d)(?=[": <])', '', html)
+
   def FixAll(self):
     self.FixTableHeadings()
     self.RemoveTopHeadings()
-
-  def __str__(self):
-    return str(self.soup)
+    html = str(self.soup)
+    html = self.RemoveVersionNumbers(html)
+    return html
 
 
-def main():
-  '''Main entry for the doxy_cleanup utility
+def main(argv):
+  """Main entry for the doxy_cleanup utility
 
-  doxy_cleanup takes a list of html files and modifies them in place.'''
+  doxy_cleanup cleans up the html files generated by doxygen.
+  """
 
-  parser = optparse.OptionParser(usage='Usage: %prog [options] files...')
+  parser = optparse.OptionParser(usage='Usage: %prog [options] directory')
+  parser.add_option('-v', '--verbose', help='verbose output.',
+                    action='store_true')
+  options, files = parser.parse_args(argv)
 
-  parser.add_option('-m', '--move', dest='move', action='store_true',
-                    default=False, help='move html files to "original_html"')
+  if len(files) != 1:
+    parser.error('Expected one directory')
 
-  options, files = parser.parse_args()
+  if options.verbose:
+    Trace.verbose = True
 
-  if not files:
-    parser.print_usage()
-    return 1
+  root_dir = files[0]
+  html_dir = os.path.join(root_dir, 'html')
 
-  for filename in files:
-    try:
-      with open(filename, 'r') as file:
-        html = file.read()
+  # Doxygen puts all files in an 'html' directory.
+  # First, move all files from that directory to root_dir.
+  for filename in glob.glob(os.path.join(html_dir, '*')):
+    Trace('Moving %s -> %s' % (filename, root_dir))
+    shutil.move(filename, root_dir)
 
-      print "Processing %s" % filename
-      fixer = HTMLFixer(html)
-      fixer.FixAll()
-      with open(filename, 'w') as file:
-        file.write(str(fixer))
-      if options.move:
-        new_directory = os.path.join(
-            os.path.dirname(os.path.dirname(filename)), 'original_html')
-        if not os.path.exists(new_directory):
-          os.mkdir(new_directory)
-        shutil.move(filename, new_directory)
-    except:
-      print "Error while processing %s" % filename
-      raise
+  # Now remove the 'html' directory.
+  Trace('Removing %s' % html_dir)
+  os.rmdir(html_dir)
+
+  # Then remove unneeded files.
+  for wildcard in FILES_TO_REMOVE:
+    Trace('Removing "%s":' % wildcard)
+    path = os.path.join(root_dir, wildcard)
+    for filename in glob.glob(path):
+      Trace('  Removing "%s"' % filename)
+      os.remove(filename)
+
+  # Now, fix the HTML files we've kept.
+  Trace('Fixing HTML files...')
+  for root, _, files in os.walk(root_dir):
+    for filename in files:
+      if not os.path.splitext(filename)[1] == '.html':
+        Trace('Skipping %s' % filename)
+        continue
+
+      filename = os.path.join(root, filename)
+      Trace('Processing "%s"...' % filename)
+      try:
+        with open(filename) as f:
+          html = f.read()
+
+        fixer = HTMLFixer(html)
+        output = fixer.FixAll()
+        with open(filename, 'w') as f:
+          f.write(output)
+      except:
+        sys.stderr.write("Error while processing %s\n" % filename)
+        raise
 
   return 0
 
 if __name__ == '__main__':
-  sys.exit(main())
+  try:
+    rtn = main(sys.argv[1:])
+  except KeyboardInterrupt:
+    sys.stderr.write('%s: interrupted\n' % os.path.basename(__file__))
+    rtn = 1
+  sys.exit(rtn)