From 7c7d3f40102764a5ad0e46d35ff23bfd7f0340f8 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Sat, 12 Jun 2010 18:16:18 +0200
Subject: [PATCH] Added ``exclude`` argument to :func:`.autodoc.between`.  From
 http://bitbucket.org/mfperzel/sphinx-additions.

---
 CHANGES               |  1 +
 sphinx/ext/autodoc.py | 11 ++++++-----
 tests/test_autodoc.py | 16 ++++++++++++++--
 3 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/CHANGES b/CHANGES
index af0a3ef1c..82308bb23 100644
--- a/CHANGES
+++ b/CHANGES
@@ -143,6 +143,7 @@ Features added
     instead of PNG images, controlled by the
     :confval:`graphviz_output_format` config value.
   - Added ``alt`` option to :rst:dir:`graphviz` extension directives.
+  - Added ``exclude`` argument to :func:`.autodoc.between`.
 
 * Translations:
 
diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py
index 8e5c5ce94..adf08bcde 100644
--- a/sphinx/ext/autodoc.py
+++ b/sphinx/ext/autodoc.py
@@ -164,11 +164,12 @@ def cut_lines(pre, post=0, what=None):
             lines.append('')
     return process
 
-def between(marker, what=None, keepempty=False):
+def between(marker, what=None, keepempty=False, exclude=False):
     """
-    Return a listener that only keeps lines between lines that match the
-    *marker* regular expression.  If no line matches, the resulting docstring
-    would be empty, so no change will be made unless *keepempty* is true.
+    Return a listener that either keeps, or if *exclude* is True excludes, lines
+    between lines that match the *marker* regular expression.  If no line
+    matches, the resulting docstring would be empty, so no change will be made
+    unless *keepempty* is true.
 
     If *what* is a sequence of strings, only docstrings of a type in *what* will
     be processed.
@@ -178,7 +179,7 @@ def between(marker, what=None, keepempty=False):
         if what and what_ not in what:
             return
         deleted = 0
-        delete = True
+        delete = not exclude
         orig_lines = lines[:]
         for i, line in enumerate(orig_lines):
             if delete:
diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py
index 62768b202..8f983471c 100644
--- a/tests/test_autodoc.py
+++ b/tests/test_autodoc.py
@@ -271,7 +271,7 @@ def test_docstring_processing():
     app.disconnect(lid)
 
     lid = app.connect('autodoc-process-docstring', between('---', ['function']))
-    def f():
+    def g():
         """
         first line
         ---
@@ -279,9 +279,21 @@ def test_docstring_processing():
         ---
         third line
         """
-    assert process('function', 'f', f) == ['second line', '']
+    assert process('function', 'g', g) == ['second line', '']
     app.disconnect(lid)
 
+    lid = app.connect('autodoc-process-docstring', between('---', ['function'],
+                                                           exclude=True))
+    def h():
+        """
+        first line
+        ---
+        second line
+        ---
+        third line
+        """
+    assert process('function', 'h', h) == ['first line', 'third line', '']
+    app.disconnect(lid)
 
 def test_new_documenter():
     class MyDocumenter(ModuleLevelDocumenter):