Qualtran icon indicating copy to clipboard operation
Qualtran copied to clipboard

Consistent formatting for references to the literature

Open mpharrigan opened this issue 1 year ago • 1 comments

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.

mpharrigan avatar Jul 19 '23 00:07 mpharrigan