Docserver: Fix the TOC rendering for API references by fixing the haphazard way

chrome/common/extensions/docs/server2/document_parser.py

 # Copyright 2013 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.
 
 from HTMLParser import HTMLParser
 import logging
 
 
 class ParseResult(object):
   '''The result of |ParseDocument|:
@@ skipping 30 matching lines @@
   '''
 
   def __init__(self, tag, attributes):
     self.attributes = attributes
     self.name = ''
     self.entries = []
     # Callers shouldn't care about the tag, but we need it for sanity checking,
     # so make it private. In particular we pretend that anything but the first
     # h1 is an h2, and it'd be odd to expose that.
     self._tag = tag
+    # Documents can override the name of the entry using title="".
+    self._has_explicit_name = False
 
   def __repr__(self):
     return '<%s>%s</%s>' % (self._tag, self.name, self._tag)
 
   def __str__(self):
     return repr(self)
 
 
 def ParseDocument(document, expect_title=False):
   '''Parses the title and a document structure form |document| and returns a
@@ skipping 57 matching lines @@
       return
 
     if tag != 'h1' and tag not in _HEADER_TAGS:
       return
 
     if self._processing_entry is not None:
       self._WarnWithPosition('Found <%s> in the middle of processing a <%s>' %
                              (tag, self._processing_entry._tag))
       return
 
-    self._processing_entry = DocumentStructureEntry(tag, dict(attrs))
+    attrs_dict = dict(attrs)
+    self._processing_entry = DocumentStructureEntry(tag, attrs_dict)
+
+    explicit_name = attrs_dict.pop('title', None)
+    if explicit_name == '':
+      # The document can specify title="" to ignore the TOC entry entirely.

[Yoyo Zhou, 2013/12/10 23:48:23]

The wording is a little confusing - how about something like:
Don't create a TOC entry at all if the tag has specified title=""

[not at google - send to devlin, 2013/12/11 22:23:23]

Done.

+      return
+    if explicit_name is not None:
+      self._processing_entry.name = explicit_name
+      self._processing_entry._has_explicit_name = True
 
     if tag == 'h1' and self._title_entry is not None:
       self._WarnWithPosition('Found multiple <h1> tags. Subsequent <h1> tags '
                              'will be classified as <h2> for the purpose of '
                              'the structure')
       tag = 'h2'
 
     if tag == 'h1':
       self._title_entry = self._processing_entry
     else:
@@ skipping 23 matching lines @@
 
     if self._processing_entry._tag != tag:
       self._WarnWithPosition('Found closing </%s> while processing a <%s>' %
                              (tag, self._processing_entry._tag))
       # Note: no early return, it's more likely that the mismatched header was
       # a typo rather than a misplaced closing header tag.
 
     self._processing_entry = None
 
   def handle_data(self, data):
-    if self._processing_entry is not None:
+    if (self._processing_entry is not None and
+        not self._processing_entry._has_explicit_name):
       # += is inefficient, but probably fine here because the chances of a
       # large number of nested tags within header tags is pretty low.
       self._processing_entry.name += data
 
   def close(self):
     HTMLParser.close(self)
 
     self._OnSectionBoundary()
 
     if self._processing_entry is not None:
@@ skipping 18 matching lines @@
 
   def _OnSectionBoundary(self):
     # Only start a new section if the previous section was non-empty.
     if self._processing_section.structure:
       self._sections.append(self._processing_section)
       self._processing_section = DocumentSection()
 
   def _WarnWithPosition(self, message):
     line, col = self.getpos()
     self._warnings.append('%s (line %s, column %s)' % (message, line, col + 1))