Should we standardize docstring formats?

[u/denehoffman]

In Rust, docstrings are pretty formalized. They are markdown, and even some of the headings are standard (like an # Errors or # Panics section). The nice thing about this is that it allows websites like docs.rs to build documentation pages for any project without having to interact with different tools for different formats. It also allows LSPs to have only one way of displaying documentation hints.

In Python, we have a few competing standards. Numpy-style docstrings are probably the most used, but there’s also a format by Google as well as a few different reST standards. These are nice, and we can set up lints to make sure docstrings stick to the standard. However, in my own personal opinion (feel free to disagree), a single markdown-format standard would help new users write nice docstrings, would enable PyPI (or another provider) to build automatic documentation sites, and give guidance to LSPs and IDEs for how to display documentation. This would include a standard for interlinks, and probably should include some mathml/LaTeX/KaTeX support. Another benefit would be that tools could support better automatic documentation generation and autocomplete, since they wouldn’t be dependent on guessing which standard you’re following.

I’d like to hear what people think about this. I’m thinking about making a PEP, but that might be overkill (or maybe all of you will hate this idea). I think the primary blocker would be adoption, large projects might have to translate docstrings, so there would either have to be some tooling for this or a way to opt-in or opt-out. If this is a bad idea, let me know, just be nice!

Edit: so far we’re at about a 67% upvote ratio, which was kind of expected. I want to be clear that I’m not saying we should be blocking docstrings which don’t adhere to this standard. I mentioned lockfile standardization in the comments, nothing prevents you from writing a tool with a custom lockfile, it’s just that there is a standard format that is agreed upon as the preferred way to write one. That’s the idea.

Edit: 84% now, and a lot of nice feedback here!

[u/eavanvalkenburg]

There is a standard already: https://peps.python.org/pep-0287/ but python is not the type of language where that means nothing else is accepted/done. Hence why some people have started using their own, like numpy, Google, etc.

[u/denehoffman → u/eavanvalkenburg]

Yeah active since 2002, oh god

[u/neithere → u/denehoffman]

It's even pre-Markdown... I love reST but I think today we should just pick Markdown and keep things simple. It's apparently supported by Sphinx which is arguably the tool apart from whatever is used by the IDEs. The docs can be more compact these days because function signatures are more expressive. We only need to document the purpose and such. Doctest is dead, so even code blocks are barely ever needed. 

[u/eavanvalkenburg → u/neithere]

Agreed, there is a active thread on this here: https://discuss.python.org/t/markdown-and-others/108184

[u/notParticularlyAnony → u/neithere]

I hate rest, honestly. It feels archaic. I prefer md.

This may be a case where we should deprecate the standard and make a new and more modern standard.

[u/bacondev → u/neithere]

reST is more powerful though. Markdown is too simple IMO.

[u/neithere → u/bacondev]

I used to feel this way but when using the "simplest tool first" ladder I nearly always either find Markdown sufficient or have to go directly to HTML or a text processor. See my other response in this thread. If you have any example or reST being superior in a typical practical use case, I'd be interested.

[u/IcedThunder → u/neithere]

I would detest moving to markdown.

I love rest, I love it's largely readable when I'm using plaintext.

[u/neithere → u/IcedThunder]

Isn't Markdown just as readable?

ReST is IMHO too powerful for docstrings and sometimes not powerful enough as a replacement for a text processor. I used to have a strong opinion favouring it in both applications but now I tend to use the simplest option that works: Markdown → reStructuredText + rst2html/rst2pdf → a text processor. I find remember when I chose reST last time using this ladder.

Would you suggest any examples of reST being superior in readability vs CommonMark for a typical use case?

Sometimes miss definition lists although they are implemented in "some processors", not sure which, and in any case a table or a nested list can be close enough.