Open mpharrigan opened 1 year 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
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. Thetensorflow_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 thattensorflow_docs
emits.For the actual citations, I propose a nice concise, webby-markdown style:
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
References
section in a pretty way that works for multiple referencestensorflow_docs
process the references section correctly as well.