## Stream: general

### Topic: documentation

#### 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 group_theory/quotient_group.

https://gist.github.com/kbuzzard/0b5a31f5a362cb32d787bc5059ed4b9d

#### 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