[rule] Mixing attribute docstrings and doc comments

Summary

Background

Attribute docstrings are a string literal after an assignment, e.g.

self.dog = get_snowball()
"""Initialized to snowball"""

Sphinx has its own, special syntax called doc comments with specially formatted comments:

#: doc comments precede if at the same indentation level
self.dog = get_snowball()

self.hog = get_babe()  #: but they can also be inline

Proposal I am going to assert that if a project uses attribute comments they've standardized on one format or the other. It would be helpful if there was a lint that could enforce their style choice.

Discussion Attribute docstrings have some amount of support in the Python community: there were PEPs 224 and 727 (both rejected). Sphinx, Pyright and Jedi all have support for attribute docstrings. Issue #10347 in this repo has moderate community approval. The doc comments syntax, however, is only supported by Sphinx, and I don't think it has broad community use at all. There's an argument for using attribute docstrings as a default if a default has to be chosen.

Personally, I had no idea doc comments were even a thing, I thought they were LLM hallucinations. I don't know if I've ever seen them in use in an open source project. There's an argument to be made that they should be considered obsolete and rejected on sight.

Uses The lint prevents documentation rendering bugs if a project with doc comments switches away from Sphinx without converting all comments to strings. It could also be used to drive a project-wide migration from one format to the other. A project that's settled on one choice can use the lint to keep the other type from creeping back into a codebase. And if you consider doc comments to be a bug it'll keep them out of your project.

And interestingly, in our modern era of LLMs, the LLMs like to mimic the commenting style already present in a file. We had a clanker introduce doc comments on accident in one file and later sessions who happened to read parts of that file started writing all their comments as doc comments too. By the time this was noticed by humans we had doc comments virally spreading from file to file in the project. This lint would have stopped a viral outbreak of doc comments.

Open Questions Is this two conflicting lints (one for each style) or a formatter configuration?

Is it time to declare doc comments dead and just add a single lint to forbid doc comments?