Kevin Buzzard (Jul 11 2019 at 14:13):
We're in VU talking about documentation. Here's a gist containing a preliminary documentation attempt for
Johan Commelin (Jul 11 2019 at 15:38):
I think the summaries at the top are useful. On the other hand, I feel like many of the docstrings don't add too much value. Their content can usually be inferred from the name of the declaration, can't it?
matt rice (Jul 14 2019 at 17:03):
@Kevin Buzzard mostly formatting nitpicks, in the summary at the top there is some expressions not wrapped in e.g. φ : G → H, where in the docstrings below the same expression wrapped in
φ : G → H. The main thing of note is that in the first case G and H are going to possibly end up using different fonts for G and H.
The only other thought deals with the References section in the summary, I don't believe i have implemented it yet, but in lumpy it shouldn't be too difficult to enable the footnotes extension, I'd probably do so by changing the comment_format field to comment_format = "cmark+footnotes" or comment_format=["cmark", "footnotes"]. It is a simple addition to implement. The main issue being deciding on whether we should accept the format, and diverse tooling issues e.g. would vscode tooltip's handle it gracefully?
Last updated: May 13 2021 at 19:20 UTC