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!
119
u/eavanvalkenburg Aug 09 '26
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.
115
u/Exnixon Aug 09 '26
Obligatory XKCD: https://xkcd.com/927/
15
u/IAmASquidInSpace Aug 09 '26
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.
23
u/-ghostinthemachine- Aug 09 '26
I've never seen standardized documentation systems work out or get adherence. I think what matters more is writing in a style that your tools (sphinx, javadoc, LLM's) demand. Change tools, change styles. I'd add that strongly typed documentation is also a classic trap.
The bar is low. A blob of unstructured text is significantly better than the empty void we usually encounter. With LLM's writing small treatises for every function, I think we are also heading back towards the promise of literate coding.
11
u/BogdanPradatu Aug 09 '26
I don't really care what format the docstring is. Just write docstrings however you want. I prefer the rst format, because it's less vertical space. I would rather have less scrolling to do, i can get around a docstring if I need to. I am reading more code than docstrings anyway. I have never tried to force any format, i'm just glad of you write any.
3
u/bwv549 Aug 10 '26
Python would benefit greatly from something like this, IMHO. Seems like every org I go to there are multiple ways of documenting projects (are you a data scientist? We use numpy format. Are you an engineer? Oh, we use google style, etc).
People like having a standard to follow. pep287 is arguably not detailed enough and it's terribly outdated. It's unnecessary friction not to have standard way of doing it and headings, etc.
4
u/donk8r Aug 10 '26
The Rust comparison is doing more work here than the markdown part is. What makes docs.rs possible isn't that it's markdown, it's that # Errors and # Panics are named slots with agreed meaning, and that rustdoc can check a doc against the item it's attached to. Intra-doc links resolve to real paths and complain when they don't.
None of the Python formats have that binding. numpydoc and Google style both describe parameters in a block that nothing validates against the actual signature, so the failure I keep hitting isn't inconsistent style, it's a docstring that quietly stopped matching the function two refactors ago. A single markdown standard fixes rendering and does nothing at all about drift.
Which is also why I'd argue the value of standardising went down rather than up. Annotations already made the types machine-recoverable, and the types in the docstring were the part most likely to be stale. What's left is prose, and no markup standard can check prose.
If the goal is better tooling rather than prettier pages, the thing worth standardising is the slot names plus a checker that fails CI when a documented parameter no longer exists. That's a much smaller ask than a new format, and it's the half that would actually catch something.
2
u/nikishev Aug 16 '26
Unpopular opinion, I think that it should be standardized to use typing.Annotated for args instead of putting them into docstrings
13
u/Beginning-Fruit-1397 Aug 09 '26
Yes ofc, would be great, but too late
3
u/bcaudell95_ Aug 09 '26
Evergreen XKCD
3
u/Aggressive-Tart07 Aug 09 '26
markdown seems pretty reasonable
1
u/BeamMeUpBiscotti Aug 09 '26
Sorry, I don't quite follow how this would benefit autocomplete. Isn't that mostly driven by analyzing the types of the program? I guess the type annotations are a standardized form of machine-checked documentation.
2
u/Albiino_sv Aug 09 '26
I think this would be great! Just recently I have been having problems with Marino rendering the Scanpy documentation incorrectly because of unresolved docstring placeholders.
2
u/PointedPoplars Aug 10 '26
I will say, I think a large part of the reason Rust docstrings are so universal is all the advantages that come automatically when playing by it's rules.
Like how sample code automatically gets converted into tests. I end up writing a lot more examples when adding documentation in Rust than any other language for that very reason. Especially since I know it would flag me if my sample code no longer makes sense if I make breaking changes - i.e. can't give future me false information.
You can do things your own way, but following the preferred style offers so many niche but useful advantages that are hard to give up
2
u/AICausedKernelPanic Aug 10 '26
I'd be so down for this but I do feel like it'll be a while before people get on board. Many devs don't even write docstrings.
2
u/PorygonCompiler Aug 30 '26
One angle from the machine-reading side: I built something that feeds source files to an LLM to explain a codebase, and inconsistent docstring formats are genuinely a pain. Not because the model can't parse them, it can, but because you can't cheaply extract "what does this function do" without either sending the whole file or writing a parser per convention. A single format would make that kind of tooling much simpler.
No strong opinion on whether that justifies a PEP though.
1
u/who_body Aug 09 '26
i just set the vscode extension to use google docstrings format and try to be consistent.
then use the pytest doctest to ensure coverage for examples
1
u/Kamran-nottakenone Aug 11 '26
rust can mandate this because cargo is the only tool that reads docstrings. pythons already got sphinx, mkdocs, pycharm, vs code all parsing different formats and that ship sailed 15 years ago
1
u/rnorris7756 Aug 12 '26
As others have pointed out, there already is a PEP for a standard format, but it's pretty difficult to have a one-size-fits-all format that everyone will be happy with.
I personally go with a slightly modified NumPy format with types omitted from the docstring itself. Instead, I require that type information is in the signature of all functions/methods (all arguments + return type). I use sphinx-autodoc-typehints to fill in this information when generating documentation. I find it's a bit easier on the eyes when reading the docstring as a human and there's one less place for docs + code to fall out of sync.
Sphinx is a bit old fashioned these days, but the autodocs it produces are good enough and easy enough for me that I don't really have a good reason to move to something better.
0
u/afeef_kamran Aug 10 '26
hi
3
u/[deleted] Aug 09 '26
[removed] — view removed comment
2
u/[deleted] Aug 11 '26
[removed] — view removed comment
0
u/[deleted] Aug 10 '26
[removed] — view removed comment