Ensure reference renaming is parallel-safe

This prefixes each reference with a token indicative of which docstring it belongs to and then relabels the text of the reference once the doctree is compiled

Author: jnothman

Diff for: numpydoc/numpydoc.py

@@ -24,6 +24,7 @@
 import sphinx
 import inspect
 import collections
+import hashlib
 
 if sphinx.__version__ < '1.0.1':
     raise RuntimeError("Sphinx 1.0.1 or newer is required")
@@ -36,9 +37,9 @@
     sixu = lambda s: unicode(s, 'unicode_escape')
 
 
-def rename_references(app, what, name, obj, options, lines,
-                      reference_offset=[0]):
-    # replace reference numbers so that there are no duplicates
+def rename_references(app, what, name, obj, options, lines):
+    # decorate reference numbers so that there are no duplicates
+    # these are later undecorated in the doctree, in relabel_references
     references = set()
     for line in lines:
         line = line.strip()
@@ -48,19 +49,41 @@ def rename_references(app, what, name, obj, options, lines,
             references.add(m.group(1))
 
     if references:
-        for r in references:
-            if r.isdigit():
-                new_r = sixu("R%d") % (reference_offset[0] + int(r))
-            else:
-                new_r = sixu("%s%d") % (r, reference_offset[0])
+        # we use a hash to mangle the reference name to avoid invalid names
+        sha = hashlib.sha256()
+        sha.update(name.encode('utf8'))
+        prefix = 'R' + sha.hexdigest()
 
+        for r in references:
+            new_r = prefix + '-' + r
             for i, line in enumerate(lines):
                 lines[i] = lines[i].replace(sixu('[%s]_') % r,
                                             sixu('[%s]_') % new_r)
                 lines[i] = lines[i].replace(sixu('.. [%s]') % r,
                                             sixu('.. [%s]') % new_r)
 
-        reference_offset[0] += len(references)
+
+def relabel_references(app, doc):
+    # Change name_ref to ref in label text
+    from docutils.nodes import citation, Text
+    from sphinx.addnodes import pending_xref
+    for citation_node in doc.traverse(citation):
+        label_node = citation_node[0]
+        new_text = Text(citation_node['names'][0].split('-')[-1])
+        label_node.replace(label_node[0], new_text)
+
+        for id in citation_node['backrefs']:
+            ref = doc.ids[id]
+            ref_text = ref[0]
+
+            # Sphinx has created pending_xref nodes with [reftext] text.
+            def matching_pending_xref(node):
+                return (isinstance(node, pending_xref) and
+                        node[0].astext() == '[%s]' % ref_text)
+
+            for xref_node in ref.parent.traverse():
+                xref_node.replace(xref_node[0], Text('[%s]' % new_text))
+            ref.replace(ref_text, new_text.copy())
 
 
 DEDUPLICATION_TAG = ['..', '    processed by numpydoc']
@@ -137,6 +160,7 @@ def setup(app, get_doc_object_=get_doc_object):
 
     app.connect('autodoc-process-docstring', mangle_docstrings)
     app.connect('autodoc-process-signature', mangle_signature)
+    app.connect('doctree-read', relabel_references)
     app.add_config_value('numpydoc_edit_link', None, False)
     app.add_config_value('numpydoc_use_plots', None, False)
     app.add_config_value('numpydoc_show_class_members', True, True)