quantumlib / Qualtran

Qᴜᴀʟᴛʀᴀɴ is a Python library for expressing and analyzing Fault Tolerant Quantum algorithms.
https://qualtran.readthedocs.io/en/latest/
Apache License 2.0
146 stars 39 forks source link

Consistent formatting for references to the literature #325

Open mpharrigan opened 1 year ago

mpharrigan commented 1 year ago

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

mpharrigan commented 3 months ago

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