False positive when documenting dataclass attributes for Sphinx

[darosio]

Hi 👋

dataclass definiiton like

@dataclass
class ObjsParams:
    """Parameters for something."""

    #: Maximum number of objects to generate
    max_num_objects: int = 8
    #: Number of rows in the image frame
    nrows: int = 128

raises DOC601 and DOC603 errors. But it is a common practice to document dataclasses using Sphinx.

[jsh9]

Hi @darosio ,

I've found that the correct Sphinx docstring format for class attributes is like this: https://jsh9.github.io/pydoclint/checking_class_attributes.html#3-sphinx-style

Does it align with your understanding of the Sphinx style?

[darosio]

Hi, Actually I do use numpy style https://jsh9.github.io/pydoclint/checking_class_attributes.html#1-numpy-style I meant when you run sphinx build you can either use docstring like in my example or in the main docstring as pydoclint is currently forcing to do. – dan

…

On Tue 25 Jun 2024 at 00:52, jsh9 ***@***.***> wrote: DuckDuckGo removed one tracker. More Report Spam Hi @darosio , I've found that the correct Sphinx docstring format for class attributes is like this: https://jsh9.github.io/pydoclint/checking_class_attributes.html#3-sphinx-style Does it align with your understanding of the Sphinx style? — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

[jsh9]

Hi @darosio , sorry for the late reply.

I think the documentation style you showed above may be impractical to parse by pydoclint, because those are considered inline comments rather than docstrings.

I'll close this issue as "no plans to implement". If compelling evidence (e.g., this style is widely used) surfaces in the future, I can consider reopening this.