add (possibly slightly off) source lines to mangled docstrings.

numpydoc/numpydoc.py

@@ -29,7 +29,6 @@
     raise RuntimeError("Sphinx 1.0.1 or newer is required")
 
 from .docscrape_sphinx import get_doc_object, SphinxDocString
-from sphinx.util.compat import Directive
 
 if sys.version_info[0] >= 3:
     sixu = lambda s: s
@@ -139,7 +138,7 @@ def setup(app, get_doc_object_=get_doc_object):
     # Extra mangling domains
     app.add_domain(NumpyPythonDomain)
     app.add_domain(NumpyCDomain)
-    
+
     metadata = {'parallel_read_safe': True}
     return metadata
 
@@ -190,6 +189,62 @@ class NumpyCDomain(ManglingDomainBase, CDomain):
     }
 
 
+def match_items(lines, content_old):
+    """Create items for mangled lines.
+
+    This function tries to match the lines in ``lines`` with the items (source
+    file references and line numbers) in ``content_old``. The
+    ``mangle_docstrings`` function changes the actual docstrings, but doesn't
+    keep track of where each line came from. The manging does many operations
+    on the original lines, which are hard to track afterwards.
+
+    Many of the line changes come from deleting or inserting blank lines. This
+    function tries to match lines by ignoring blank lines. All other changes
+    (such as inserting figures or changes in the references) are completely
+    ignored, so the generated line numbers will be off if ``mangle_docstrings``
+    does anything non-trivial.
+
+    This is a best-effort function and the real fix would be to make
+    ``mangle_docstrings`` actually keep track of the ``items`` together with
+    the ``lines``.
+
+    Examples
+    --------
+    >>> lines = ['', 'A', '', 'B', '   ', '', 'C', 'D']
+    >>> lines_old = ['a', '', '', 'b', '', 'c']
+    >>> items_old = [('file1.py', 0), ('file1.py', 1), ('file1.py', 2),
+    ...              ('file2.py', 0), ('file2.py', 1), ('file2.py', 2)]
+    >>> content_old = ViewList(lines_old, items=items_old)
+    >>> match_items(lines, content_old) # doctest: +NORMALIZE_WHITESPACE
+    [('file1.py', 0), ('file1.py', 0), ('file2.py', 0), ('file2.py', 0),
+     ('file2.py', 2), ('file2.py', 2), ('file2.py', 2), ('file2.py', 2)]
+    >>> # first 2 ``lines`` are matched to 'a', second 2 to 'b', rest to 'c'
+    >>> # actual content is completely ignored.
+
+    Notes
+    -----
+    The algorithm tries to match any line in ``lines`` with one in
+    ``lines_old``.  It skips over all empty lines in ``lines_old`` and assigns
+    this line number to all lines in ``lines``, unless a non-empty line is
+    found in ``lines`` in which case it goes to the next line in ``lines_old``.
+
+    """
+    items_new = []
+    lines_old = content_old.data
+    items_old = content_old.items
+    j = 0
+    for i, line in enumerate(lines):
+        # go to next non-empty line in old:
+        # line.strip() checks whether the string is all whitespace
+        while j < len(lines_old) - 1 and not lines_old[j].strip():
+            j += 1
+        items_new.append(items_old[j])
+        if line.strip() and j < len(lines_old) - 1:
+            j += 1
+    assert(len(items_new) == len(lines))
+    return items_new
+
+
 def wrap_mangling_directive(base_directive, objtype):
     class directive(base_directive):
         def run(self):
@@ -205,7 +260,10 @@ def run(self):
 
             lines = list(self.content)
             mangle_docstrings(env.app, objtype, name, None, None, lines)
-            self.content = ViewList(lines, self.content.parent)
+            if self.content:
+                items = match_items(lines, self.content)
+                self.content = ViewList(lines, items=items,
+                                        parent=self.content.parent)
 
             return base_directive.run(self)