sphinxext: use real RST references for bibliographies, and add suitable links for Latex

3 files changed, 31 insertions, 17 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 4923db977..380282219 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -14,7 +14,7 @@ if sphinx.__version__ < "0.5":
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 
-sys.path.append(os.path.abspath('../sphinxext'))
+sys.path.insert(0, os.path.abspath('../sphinxext'))
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc',
               'sphinx.ext.intersphinx', 'sphinx.ext.coverage',
diff --git a/doc/sphinxext/docscrape_sphinx.py b/doc/sphinxext/docscrape_sphinx.py
index 77ed271b0..7293fc795 100644
--- a/doc/sphinxext/docscrape_sphinx.py
+++ b/doc/sphinxext/docscrape_sphinx.py
@@ -1,4 +1,5 @@
 import re, inspect, textwrap, pydoc
+import sphinx
 from docscrape import NumpyDocString, FunctionDoc, ClassDoc
 
 class SphinxDocString(NumpyDocString):
@@ -90,6 +91,18 @@ class SphinxDocString(NumpyDocString):
                 self['References'] = [self['References']]
             out.extend(self['References'])
             out += ['']
+            # Latex collects all references to a separate bibliography,
+            # so we need to insert links to it
+            if sphinx.__version__ >= 0.6:
+                out += ['.. only:: latex','']
+            else:
+                out += ['.. latexonly::','']
+            items = []
+            for line in self['References']:
+                m = re.match(r'.. \[([a-z0-9._-]+)\]', line, re.I)
+                if m:
+                    items.append(m.group(1))
+            out += ['   ' + ", ".join(["[%s]_" % item for item in items]), '']
         return out
 
     def __str__(self, indent=0, func_role="obj"):
diff --git a/doc/sphinxext/numpydoc.py b/doc/sphinxext/numpydoc.py
index 926667dc0..edd58597f 100644
--- a/doc/sphinxext/numpydoc.py
+++ b/doc/sphinxext/numpydoc.py
@@ -22,6 +22,7 @@ import inspect
 
 def mangle_docstrings(app, what, name, obj, options, lines,
                       reference_offset=[0]):
+
     if what == 'module':
         # Strip top title
         title_re = re.compile(r'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*',
@@ -43,25 +44,25 @@ def mangle_docstrings(app, what, name, obj, options, lines,
 
     # replace reference numbers so that there are no duplicates
     references = []
-    for l in lines:
-        l = l.strip()
-        if l.startswith('.. ['):
-            try:
-                references.append(int(l[len('.. ['):l.index(']')]))
-            except ValueError:
-                print "WARNING: invalid reference in %s docstring" % name
-
-    # Start renaming from the biggest number, otherwise we may
-    # overwrite references.
-    references.sort()
+    for line in lines:
+        line = line.strip()
+        m = re.match(r'^.. \[([a-z0-9_.-])\]', line, re.I)
+        if m:
+            references.append(m.group(1))
+
+    # start renaming from the longest string, to avoid overwriting parts
+    references.sort(key=lambda x: -len(x))
     if references:
         for i, line in enumerate(lines):
             for r in references:
-                new_r = reference_offset[0] + r
-                lines[i] = lines[i].replace('[%d]_' % r,
-                                            '[%d]_' % new_r)
-                lines[i] = lines[i].replace('.. [%d]' % r,
-                                            '.. [%d]' % new_r)
+                if re.match(r'^\d+$', r):
+                    new_r = "R%d" % (reference_offset[0] + int(r))
+                else:
+                    new_r = "%s%d" % (r, reference_offset[0])
+                lines[i] = lines[i].replace('[%s]_' % r,
+                                            '[%s]_' % new_r)
+                lines[i] = lines[i].replace('.. [%s]' % r,
+                                            '.. [%s]' % new_r)
 
     reference_offset[0] += len(references)