add call outs to all references in docstrings

#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.

[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.

[souravsingh]

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