Qualtran
Qualtran copied to clipboard
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
References
section in a pretty way that works for multiple references - [ ] Bonus: make
tensorflow_docs
process the references section correctly as well.