md_browser: Implement Gitiles blocks notation.

tools/md_browser/gitiles_ext_blocks.py

Index: tools/md_browser/gitiles_ext_blocks.py
diff --git a/tools/md_browser/gitiles_ext_blocks.py b/tools/md_browser/gitiles_ext_blocks.py
new file mode 100644
index 0000000000000000000000000000000000000000..c474ba99edd76df03ea8dc96cdf140a3d137dbbd
--- /dev/null
+++ b/tools/md_browser/gitiles_ext_blocks.py
@@ -0,0 +1,77 @@
+# 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.
+
+"""Implements Gitiles' notification, aside and promotion blocks.
+
+This extention makes the Markdown parser recognize the Gitiles' extended
+blocks notation. The syntax is explained at:
+
+https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Notification_aside_promotion-blocks
+"""
+
+
+from markdown.blockprocessors import BlockProcessor
+from markdown.extensions import Extension
+from markdown.util import etree

[nodir, 2015/10/20 14:53:39]

there are style inconsistencies in this file, such as blank lines above and that
you import classes instead of modules, but dpranke@ is more appropriate to
review style

[Dirk Pranke, 2015/10/20 22:42:16]

I'm fine w/ importing classes directly. 

[Yuta Kitamura, 2015/10/21 04:36:48]

Thanks, I dropped one blank line from the blanks above.

(I researched the number of blank lines after the end of module
documentation, but it wasn't really consistent: 0, 1 or 2 lines.
One blank line seemed majority, so I followed that.)

+import re
+
+
+class GitilesExtBlockProcessor(BlockProcessor):

[Dirk Pranke, 2015/10/20 22:42:16]

Nit: I'd name this _GitilesExtBlockProcessor, since it doesn't need to be a
public class.

[Yuta Kitamura, 2015/10/21 04:36:48]

Done.

+  """Process Gitiles' notification, aside and promotion blocks."""
+
+  RE_START = re.compile(r'^\*\*\* (note|aside|promo)\n')

[nodir, 2015/10/20 14:53:39]

there may be trailing space

[Yuta Kitamura, 2015/10/21 04:36:48]

Done.

+  RE_END = re.compile(r'\n\*\*\*(?:\n|$)')

[nodir, 2015/10/20 14:53:39]

here too

[Yuta Kitamura, 2015/10/21 04:36:48]

Done.

+
+  def __init__(self, *args, **kwargs):
+    self.__last_parents = []

[Dirk Pranke, 2015/10/20 22:42:16]

why is this a list? it seems like having nested blocks isn't allowed, so you
could probably make this a single element and just assert that it is empty on
match start and not empty on match end.

Also, as a nit, I don't usually recommend using __var for private variable
members; the name mangling Python does to ensure privacy is not usually needed
and makes things a bit harder to use. 

[Yuta Kitamura, 2015/10/21 04:36:48]

My first assumption was that these blocks were nestable, but
I now think nested blocks are not really useful, so I've changed
this list to a variable.

Renamed __last_parents to _last_parent.

Asserting on inconsistency is probably not desirable; if we did so,
broken documentation can abort the local web server. Instead, we
probably should keep parsing even if the results are corrupted.

+    BlockProcessor.__init__(self, *args, **kwargs)

[Dirk Pranke, 2015/10/20 22:42:16]

Nit: I'd probably do super(GitilesExtBlockProcessor, self)(*args, **kwargs)
instead, but it doesn't matter much.

[Yuta Kitamura, 2015/10/21 04:36:48]

I first did it that way but that didn't work, because BlockProcessor is not a
"new style"
class, i.e. it does not inherit from object.

[Dirk Pranke, 2015/10/21 19:12:51]

ok.

+
+  def test(self, parent, block):
+    return self.RE_START.search(block) or self.RE_END.search(block)
+
+  def run(self, parent, blocks):
+    raw_block = blocks.pop(0)
+    match_start = self.RE_START.search(raw_block)
+    if match_start:
+      # Opening a new block.
+      rest = raw_block[match_start.end():]
+
+      div = etree.SubElement(parent, 'div')
+      # Setting the class name is sufficient, because doc.css already has
+      # styles for these classes.
+      div.set('class', match_start.group(1))
+      self.__last_parents.append(parent)
+      blocks.insert(0, rest)
+      self.parser.parseBlocks(div, blocks)
+      return
+
+    match_end = self.RE_END.search(raw_block)
+    if match_end:
+      # Ending an existing block.
+
+      # Process the text preceding the ending marker in the current context
+      # (i.e. within the div block).
+      rest = raw_block[:match_end.start()]
+      self.parser.parseBlocks(parent, [rest])
+
+      if not self.__last_parents:
+        # Inconsistent state (the ending marker is found but there is no
+        # matching starting marker).
+        # Let's continue as if we did not see the ending marker.
+        return
+
+      self.parser.parseBlocks(self.__last_parents.pop(), blocks)
+      return
+
+
+class GitilesExtBlockExtension(Extension):
+  """Add Gitiles' extended blocks to Markdown."""
+  def extendMarkdown(self, md, md_globals):
+    md.parser.blockprocessors.add('gitilesextblocks',
+                                  GitilesExtBlockProcessor(md.parser),
+                                  '_begin')
+
+
+def makeExtension(*args, **kwargs):
+  return GitilesExtBlockExtension(*args, **kwargs)