[NaCl SDK Docs] Fix many issues with the doc generator.

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.
 '''
 
@@ skipping 118 matching lines @@
       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 RemoveSeparators(self):
+    '''Removes separator rows from tables
+
+    This seems to only exist in newer versions of doxygen (1.8).
+    '''
+    separator_tags = self.soup.findAll(
+        name='tr',
+        attrs={'class': re.compile(r'^separator:.*$')})
+    [tag.extract() for tag in separator_tags]
+
+  def FixFragments(self):
+    ''''''

[Sam Clegg, 2014/09/20 00:02:36]

Is this also a doxygen version thing?  Maybe mention why this is needed in the
comment.

[binji, 2014/09/22 17:54:02]

Done.

+    first = True
+    fragments = self.soup.findAll(name='div', attrs={'class': 'fragment'})
+    for fragment in fragments:
+      # Replace:
+      #  <div class="fragment">
+      #    <div class="line">...</div>
+      #
+      # With:
+      #  <div class="fragment">
+      #    ...
+      lines = fragment.findAll(name='div', attrs={'class': 'line'})
+      for line in lines:
+        line.replaceWithChildren()
+
+      # Wrap the contents of the fragment in a <pre>, but only if it isn't
+      # already there.
+      if not fragment.pre:
+        pre = Tag(self.soup, name='pre', attrs={'class': 'fragment'})
+        for el in reversed(fragment.contents):
+          pre.insert(0, el.extract())
+        fragment.append(pre)
+
   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()
+    self.RemoveSeparators()
+    self.FixFragments()
     html = str(self.soup)
     html = self.RemoveVersionNumbers(html)
     return html
 
 
 def main(argv):
   """Main entry for the doxy_cleanup utility
 
   doxy_cleanup cleans up the html files generated by doxygen.
   """
@@ skipping 26 matching lines @@
   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):
+    files.sort()
     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__':
   try:
     rtn = main(sys.argv[1:])
   except KeyboardInterrupt:
     sys.stderr.write('%s: interrupted\n' % os.path.basename(__file__))
     rtn = 1
   sys.exit(rtn)