Change [TOC] processing in MD browser to match gitiles

tools/md_browser/md_browser.py

 #!/usr/bin/env python
 # Copyright 2015 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.
 
 """Simple Markdown browser for a Git checkout."""
 from __future__ import print_function
 
 import SimpleHTTPServer
 import SocketServer
 import argparse
 import codecs
 import os
 import re
 import socket
 import sys
 import threading
 import time
 import webbrowser
+from xml.etree import ElementTree
 
 
 THIS_DIR = os.path.abspath(os.path.dirname(__file__))
 SRC_DIR = os.path.dirname(os.path.dirname(THIS_DIR))
-sys.path.append(os.path.join(SRC_DIR, 'third_party', 'Python-Markdown'))
+sys.path.insert(0, os.path.join(SRC_DIR, 'third_party', 'Python-Markdown'))
 import markdown
 
 
 def main(argv):
   parser = argparse.ArgumentParser(prog='md_browser')
   parser.add_argument('-p', '--port', type=int, default=8080,
                       help='port to run on (default = %(default)s)')
   parser.add_argument('-d', '--directory', type=str, default=SRC_DIR)
   parser.add_argument('file', nargs='?',
                       help='open file in browser')
@@ skipping 113 matching lines @@
         'markdown.extensions.toc',
         'gitiles_ext_blocks',
     ]
     extension_configs = {
         'markdown.extensions.toc': {
             'slugify': _gitiles_slugify
         },
     }
 
     contents = self._Read(path[1:])
-    md_fragment = markdown.markdown(contents,
-                                    extensions=extensions,
-                                    extension_configs=extension_configs,
-                                    output_format='html4').encode('utf-8')
+
+    md = markdown.Markdown(extensions=extensions,
+                           extension_configs=extension_configs,
+                           output_format='html4')
+    md.treeprocessors['adjust_toc'] = _AdjustTOC()
+
+    md_fragment = md.convert(contents).encode('utf-8')
+
     try:
       self._WriteHeader('text/html')
       self._WriteTemplate('header.html')
       self.wfile.write(md_fragment)
       self._WriteTemplate('footer.html')
     except:
       raise
 
   def _DoCSS(self, template):
     self._WriteHeader('text/css')
@@ skipping 20 matching lines @@
     self.send_response(200)
     self.send_header('Content-Type', content_type)
     self.end_headers()
 
   def _WriteTemplate(self, template):
     contents = self._Read(os.path.join('tools', 'md_browser', template),
                           relative_to=SRC_DIR)
     self.wfile.write(contents.encode('utf-8'))
 
 
+
+class _AdjustTOC(markdown.treeprocessors.Treeprocessor):
+  def run(self, tree):
+    # A table of contents with a single H1 header is translated to
+    # <div class='toc'>
+    #   <ul>
+    #     <li>
+    #      <a>H1>
+    #      <ul>
+    #        <li>first H2
+    #        <li>second H2</li></ul></li><ul>
+    #
+    # We want to replace the first ul with the second one.
+    #
+    # Also, we want to insert an <h2>Contents and then indent

[jsbell, 2016/11/07 17:32:06]

Can you depict the "after" structure as you did the "before" structure? 

[Dirk Pranke, 2016/11/07 18:17:27]

Will do.

+    # the rest in a <div class='toc-aux'>.
+    toc_nodes = tree.findall(".//*[@class='toc']")
+    if toc_nodes:

[jsbell, 2016/11/07 17:32:06]

Maybe early return if falsy, to reduce indentation?

And/or I'd expect a loop over toc_nodes or just find()/processing the first one,
but I don't understand the else branch below so I don't know if my expectation
is correct. Is class=toc assigned to anything but the top-level TOC node?

[Dirk Pranke, 2016/11/07 18:17:27]

Good suggestion, will do.
Looks like the logic in lines 225-233 is wrong. The intent was to only flatten
the tree
if there was a single H1, otherwise to leave it alone, but that's not what it
does. Will fix.

+      if len(toc_nodes) == 1:
+        toc = toc_nodes[0]
+        toc_ul = toc[0]
+        toc_ul_li = toc_ul[0]
+        toc_ul_li_ul = toc_ul_li[1]
+        del toc[0]
+        children = toc_ul_li_ul
+      else:
+        children = list(toc)

[jsbell, 2016/11/07 17:32:06]

What is toc in this else branch, and below if this branch is taken?

(I have a feeling there's an "alternate" TOC structure that isn't illustrated
where populating children not from toc_ul_li_ul makes sense, but I don't see toc
initialized for this branch)

[Dirk Pranke, 2016/11/07 18:17:27]

See above, will fix.

+
+      while len(toc):
+          toc.remove[0]
+      contents = ElementTree.SubElement(toc, 'h2')
+      contents.text = 'Contents'
+      contents.tail = '\n'
+      toc_aux = ElementTree.SubElement(toc, 'div', attrib={'class': 'toc-aux'})
+      toc_aux.text = '\n'
+      toc_aux_ul = ElementTree.SubElement(toc_aux, 'ul')
+      toc_aux_ul.text = '\n'
+      toc_aux_ul.extend(children)
+      toc_aux_ul.tail = '\n'
+      toc_aux.tail = '\n'
+
+
 if __name__ == '__main__':
   sys.exit(main(sys.argv[1:]))