[PATCH 1 of 2] minirst: support containers

[Martin Geisler]

# HG changeset patch
# User Martin Geisler <mg at lazybytes.net>
# Date 1254686621 -7200
# Node ID 15553d2b2f9a19a216a5ccab6a861706c3d15e6c
# Parent  cad36e496640e55c19d0960c258a82540c98d501
minirst: support containers

Text can be grouped into generic containers in reStructuredText:

  .. container:: foo

     This is text inside a "foo" container.

     .. container:: bar

        This is nested inside two containers.

The minirst parser now recognizes these containers. The containers are
either pruned completely from the output (included all nested blocks)
or they are simply un-indented. So if 'foo' and 'bar' containers are
kept, the above example will result in:

     This is text inside a "foo" container.

     This is nested inside two containers.

If only 'foo' containers are kept, we get:

     This is text inside a "foo" container.

No output is made if only 'bar' containers are kept.

This feature will come in handy for implementing different levels of
help output (e.g., verbose and debug level help texts).

diff --git a/mercurial/minirst.py b/mercurial/minirst.py
--- a/mercurial/minirst.py
+++ b/mercurial/minirst.py
@@ -107,6 +107,41 @@
     return blocks
 
 
+def prunecontainers(blocks, keep):
+    """Prune unwanted containers.
+
+    The blocks must have a 'type' field, i.e., they should have been
+    run through findliteralblocks first.
+    """
+    i = 0
+    while i+1 < len(blocks):
+        # Searching for a block that looks like this:
+        #
+        # +-------+---------------------------+
+        # | ".. container ::" type            |
+        # +---+                               |
+        #     | blocks                        |
+        #     +-------------------------------+
+        if (blocks[i]['type'] == 'paragraph' and
+            blocks[i]['lines'][0].startswith('.. container::')):
+            indent = blocks[i]['indent']
+            adjustment = blocks[i+1]['indent'] - indent
+            containertype = blocks[i]['lines'][0][15:]
+            prune = containertype not in keep
+
+            # Always delete "..container:: type" block
+            del blocks[i]
+            j = i
+            while j < len(blocks) and blocks[j]['indent'] > indent:
+                if prune:
+                    del blocks[j]
+                else:
+                    blocks[j]['indent'] -= adjustment
+                    j += 1
+        i += 1
+    return blocks
+
+
 def findsections(blocks):
     """Finds sections.
 
@@ -310,12 +345,13 @@
                              subsequent_indent=subindent)
 
 
-def format(text, width, indent=0):
+def format(text, width, indent=0, keep=[]):
     """Parse and format the text according to width."""
     blocks = findblocks(text)
     for b in blocks:
         b['indent'] += indent
     blocks = findliteralblocks(blocks)
+    blocks = prunecontainers(blocks, keep)
     blocks = findsections(blocks)
     blocks = findbulletlists(blocks)
     blocks = findoptionlists(blocks)
@@ -328,8 +364,8 @@
 if __name__ == "__main__":
     from pprint import pprint
 
-    def debug(func, blocks):
-        blocks = func(blocks)
+    def debug(func, *args):
+        blocks = func(*args)
         print "*** after %s:" % func.__name__
         pprint(blocks)
         print
@@ -338,6 +374,7 @@
     text = open(sys.argv[1]).read()
     blocks = debug(findblocks, text)
     blocks = debug(findliteralblocks, blocks)
+    blocks = debug(prunecontainers, blocks, sys.argv[2:])
     blocks = debug(findsections, blocks)
     blocks = debug(findbulletlists, blocks)
     blocks = debug(findoptionlists, blocks)
diff --git a/tests/test-minirst.py b/tests/test-minirst.py
--- a/tests/test-minirst.py
+++ b/tests/test-minirst.py
@@ -2,10 +2,10 @@
 
 from mercurial import minirst
 
-def debugformat(title, text, width):
+def debugformat(title, text, width, **kwargs):
     print "%s formatted to fit within %d characters:" % (title, width)
     print "-" * 70
-    print minirst.format(text, width)
+    print minirst.format(text, width, **kwargs)
     print "-" * 70
     print
 
@@ -151,3 +151,22 @@
 
 debugformat('fields', fields, 60)
 debugformat('fields', fields, 30)
+
+containers = """
+
+Normal output.
+
+.. container:: verbose
+
+   Verbose output.
+
+   .. container:: debug
+
+      Debug output.
+"""
+
+debugformat('containers (normal)', containers, 60)
+debugformat('containers (verbose)', containers, 60, keep=['verbose'])
+debugformat('containers (debug)', containers, 60, keep=['debug'])
+debugformat('containers (verbose debug)', containers, 60,
+            keep=['verbose', 'debug'])
diff --git a/tests/test-minirst.py.out b/tests/test-minirst.py.out
--- a/tests/test-minirst.py.out
+++ b/tests/test-minirst.py.out
@@ -237,3 +237,29 @@
               significant.
 ----------------------------------------------------------------------
 
+containers (normal) formatted to fit within 60 characters:
+----------------------------------------------------------------------
+Normal output.
+----------------------------------------------------------------------
+
+containers (verbose) formatted to fit within 60 characters:
+----------------------------------------------------------------------
+Normal output.
+
+Verbose output.
+----------------------------------------------------------------------
+
+containers (debug) formatted to fit within 60 characters:
+----------------------------------------------------------------------
+Normal output.
+----------------------------------------------------------------------
+
+containers (verbose debug) formatted to fit within 60 characters:
+----------------------------------------------------------------------
+Normal output.
+
+Verbose output.
+
+Debug output.
+----------------------------------------------------------------------
+