Behaviour when using --convention

[saroad2]

This is a followup issue for #478.

The question here is how the --convention flag affects the chosen rules to be executed when evaluating doctsring. Here is my suggestion:

I think the approach should be that you should split the violations into two categories:

Global - violations which are part of the pycodestyle guidelines Convention specific - violations that are only relevant for a specific convention.

A definition of a convention-specific violation should look like:

D497 = D4xx.create_error('D497', 'This is a global rule', 'description')
D498 = D4xx.create_error(
    'D498', 'This is a sphinx rule', 'description', convention="sphinx"
)
D499 = D4xx.create_error(
    'D499',
    'This is a sphinx and google rule',
    'description',
    convention=["sphinx", "google"]
)

The global rule will be set by default with convention=None. Rules that are convention-specific will run only if --convention has been raised with their convention. Global rules will always run. In that way we can prevent false-positive for convention-specific violations

One can choose to add/ignore a violation regardless of the chosen conversion by using --add-select or --add-ignore.

What do you think?

[saroad2]

Hey, you're feedback on this will be much appreciated! Would love to add this ability.

[sambhav]

@saroad2 I am starting work on pydocstyle 6.0 which will elevate conventions to be a first class concept in the checker. I'd be more than happy to have other contributors working on this. I will be targetting the end of this year for the release. Things to do are -

1. Come up with a proposal to cause as few disruptions as possible with the existing config.
2. Refactor the checker to allow support for convention.
3. Improve false negatives/positives due to the convention detection currently being a hueristic.
4. Improve support for Google and Numpy conventions.
5. Add support for sphinx style docstrings.

We have a chat at https://gitter.im/PyCQA/pydocstyle# if you want drop by and discuss this.

[rrwalton]

Anyone currently working on support for sphinx style docstrings? I'd be happy to take a look if nobody else is.

[rrwalton]

Anyone currently working on support for sphinx style docstrings? I'd be happy to take a look if nobody else is.

Ah, just noticed https://github.com/PyCQA/pydocstyle/pull/595. Good stuff.