Fix/enhance replacement of citation reference numbers to avoid duplicates

[callegar]

This is meant to fix bug #49 and more.

Changes are meant to:

• Factor out the reference number replacement code in its own function
  • So that other extensions can replace this functionality should this be needed.
• Remove unused code from the reference number replacement routine
• Make the pattern used to identify the references configurable
  • This is meant to allow the user to decide what should be replaced. Such functionality can be extremely useful for two reasons: (i) in case the change in the default pattern (see next point) ends up breaking something and one explicitly wants the older numpydoc matching for references; and (ii), most important, to allow duplicates to be managed at a different level in sphinx.
• Change the default pattern used to identify references from [a-z0-9_.-] to [a-z0-9_.-]+
  • so that multidigit entries are recognized (e.g. [10])

[stefanv]

This looks reasonable. Did you test it on some big codebases like numpy and scipy to make sure it works fine?

/cc @pv

[callegar]

Hi, thanks for looking into the pull request.

I'm trying to test with scipy, but apparently I am having issues with the build_sphinx target. Any clue if this the recommended way to build the scipy documentation? For some reason it seems to pick up the numpy version instead of the scipy one and to mess up the CSS in the html sphinx build. In practice, I'm getting the same sort of trouble described in scipy issue 826. I'll be back as soon as I can test.

[pv]

python runtests.py -g --shell -- -c 'make -C doc html-scipyorg'

[callegar]

Thanks... with this I seem to be able to test the sphinx documentation and the html-scipyorg build succeeds. However, note that from my preliminary experiments the latex build seems to be broken (at least with the sphinx version I am using, that is 1.4.6). The latex source is produced, but it does not compile with errors ranging from incorrect unicode, to math without $...$, to lists too deeply nested. Hence, I will not be able to test the patch with the latex target, but only with the html one.

[callegar]

Tested: pull request seems OK with scipy html documentation: references remain in place and with the same number.

[rgommers]

I'll have a look at the latex build. Breaks regularly due to Sphinx changes, it's not a very stable toolchain. IIRC Sphinx 1.2.1 worked, 1.3.x broken something.

[callegar]

I know... even when the toolchain does not error out, some tables are horribly formatted in LaTeX with overfull boxes that extend out of the page... I may propose some updates to the latex writer in sphinx in that area.

[rgommers]

Didn't get the pdf tested (no space for MacTeX - will do on my linux box later), but the html looks good to me. No new warnings for the scipy build.

This looks good to me, so merging. Thanks @callegar