diff options
| -rw-r--r-- | doc/source/conf.py | 2 | ||||
| -rw-r--r-- | doc/sphinxext/docscrape_sphinx.py | 13 | ||||
| -rw-r--r-- | doc/sphinxext/numpydoc.py | 33 |
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) |