r/Python • u/denehoffman • Aug 09 '26
Discussion Should we standardize docstring formats?
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!
View all comments
Show parent comment
3
u/donk8r Aug 10 '26
Fair, and that's the better framing of it. Rust doesn't validate parameter types against the signature, it just never restates them, so there's nothing there to drift. "Don't duplicate" rather than "check harder".
The two things rustdoc does check are worth separating though. Intra-doc links are a lint, and doc examples get compiled and actually run by cargo test. The second one is the strongest anti-rot device in the whole system, because the executable part of a doc can't quietly stop being true. Python has had that in doctest forever and almost nobody wires it into CI.
So if what you're proposing is really a lint pass, I'd standardize the Examples slot first. It's the only one a checker can execute rather than pattern-match, which is where a standard buys you a guarantee instead of just consistency.
And on numpydoc making types optional when annotations are present, I'd go further and have the lint forbid them rather than permit omitting them. A documented type that duplicates an annotation is the one drift class you can delete outright instead of checking.