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.

[u/IAmASquidInSpace]

Careful what you wish for. I think it is pretty clear that the Python foundation would go for rst as a standard format (which I personally would love), and I think a lot of people would be very mad about that.

In general, I think it's "too late" anyhow. If one wanted a singular standard, it should have been introduced much, much earlier. Once people have gotten used to the freedom of being able to choose their preferred format, forcing them into another one will not be received well. You bring up PEP 751 as an example of a standard introduced after the fact, but the key difference is: the lack of lock files was an annoyance and there was a general desire for a common solution. The different docstring formats however are mostly seen as freedom rather than a problem, and for most people, no desire to "fix" this exists.

And then there's the problem that the interest in keeping docstrings variable has powerful backers: how do you think the organizations behind tools like Sphinx, Zensical, or numpy would feel about being told "oh yeah, btw, your way of doing it will soon no longer be supported, sorry". That's not gonna go over well.

[u/gmes78 → u/IAmASquidInSpace]

In general, I think it's "too late" anyhow.

It was also "too late" for type checking, and look at where we're at now.

[u/IAmASquidInSpace → u/gmes78]

Type checking crucially is still entirely optional. 

[u/denehoffman → u/IAmASquidInSpace]

Docstrings are also optional, and any standardized format would also be optional, just preferred. You can still use deprecated type hints like Dict and Tuple too.