Skip to content

Make docstring convention a global setting #9043

Description

@Mr-Pepe

Pydocstyle has a setting to specify the used docstring convention:

[tool.ruff.lint.pydocstyle]
convention = "google"

Pylint also has rules for docstrings and profits from setting the used convention. #8843 introduces one of those rules and adds a convention setting specific to Pylint.

I think that having two different settings for the convention is not very intuitive as a user and might hinder efforts to unify settings and rules later on if someone actually selects two different conventions for Pydocstyle and Pylint checks (no idea why someone would do that but there's always someone out there). Having a other tools, like a docstring formatter, in the future would further complicate things. The setting should therefore not only be global to linting, but global to all tools.

I propose to turn Pydocstyle's convention setting into a global setting to make it usable by the Pylint rules and other tools, like formatters. A strategy could look like the following:

  • Add a docstring-convention setting under [tool.ruff]
  • Deprecate the Pydocstyle setting (and Pylint's if [pylint] Add missing return doc rule (W9011) #8843 gets merged in its current form) in favor of the new setting
  • Only mention the global setting in the docs
  • Remove the original setting at some point in the future (is Ruff's deprecation process based on time or releases?)

Metadata

Metadata

Assignees

No one assigned

    Labels

    configurationRelated to settings and configuration

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions