Consistent formatting for references to the literature
Right now, many bloqs have a References: section in their docstring. This has no fixed citation format. The jupyter_autogen functionality does have a special case for this section, but it just emits a heading and then the text stripped of whitespace. The tensorflow_docs (I think) will parse all sections with a google-docstring-style heading (including References:) but we don't include any of the bloqs in the reference/API docs that tensorflow_docs emits.
For the actual citations, I propose a nice concise, webby-markdown style:
References:
[LN00]: <https://arxiv.org/abs/0000.0000> "The long and important title goes here".
LastName1 et. al. 2000
[BN01]: <https://arxiv.org/abs/0000.0000> "The long and important title goes here".
LastName1 et. al. 2001
where the short ID are the first n<=3 authors' initials and the two-digit year; link and title are as given; Up to two last names listed, otherwise one name and "et. al." and the year of the first arxiv version. The main body of the docstring can refer to a reference by its short ID
- [ ] Go through and make sure everything has a consistent and agreed-upon citation format.
- [x] Make jupyter_autogen process the
Referencessection in a pretty way that works for multiple references - [ ] Bonus: make
tensorflow_docsprocess the references section correctly as well.
The format is described here: https://qualtran.readthedocs.io/en/latest/Autodoc.html#references
There are places in the library where the regex fails and it uses the fallback, un-parsed reference. Outstanding action item is to fix these and maybe make unparsable references an error
#1613 fixed the last of these for now; but there is no check in place that would prevent new ones from sneaking in