add call outs to all references in docstrings

[wholmgren]

#833 converts all references into the numpydoc format. The unfortunate side effect of this is that it creates a lot of warnings in the sphinx build because many of the references are not called out in the docstring. #833 silences these warnings using suppress_warnings = ['ref.footnote']. In the long run, it would be great to call out the references and remove the suppress warnings statement. That would move us one step closer to automatically and comprehensively checking docstrings for style.

[souravsingh]

@wholmgren I am interested in taking a stab at the issue.

[wholmgren]

Great, thanks, let us know if you need anything to get started!

[cwhanse]

@wholmgren @souravsingh the current references are being formatted as footnotes rather than citations, since the callouts start with a numeral as the first character. Compare the footnote format to the citation format.

If we switch to citations, I think it is possible to collect references in a common source file. Worth discussing if we want to do that; it would save a lot of repeated docstring text.

[wholmgren]

@cwhanse is the only change that we use strings (e.g. _[myref]) instead of integers (e.g. _[1])? I don't see any other difference (e.g. to the conf.py file).

it would save a lot of repeated docstring text.

I can see some pros (less repetition, all references in one place) and cons (references are farther from the relevant code), but I think I'd go for it. Do you know of other projects that take this approach?

[cwhanse]

scipy uses both styles (footnote and citation), e.g. nonlin.py it appears that the style is up to the implementer. scipy puts citations with each function, and repeats the docstring text where the citation applies to more than one function. The scipy docs style avoids formatting numbered citation callouts as superscripts (footnote style), e.g. newton-krylov

I don't have a strong preference for either [1] or [Perez90]. It would be nice to not see callouts as superscripts, but that's a nice-to-have.

I'm now -1 on collecting references into a common file. That may be advantageous for documentation pages, but I see removing the references from each function is a step backwards and isn't worth the small gain of removing repeated text from docstrings.