[Feature Request] Validate sphinx parameters

[saroad2]

First of all: Awesome tool!

I think it should be beneficial if Pydocstyle would not only validate that every function and class is documented, but it would also be able to validate that all parameters are documented with Sphinx

Consider the following function:

def a_function(a, b):
    """
    This is a function.
    
    :param a: This is a parameter
    :type a: int
    :return: Returns nothing
    """
    return None

It is clear that this is not fully documented since there is no documentation for b.

This validation should be activated with a flag, something like --sphinx or --validate-parameters.

[saroad2]

From taking a little bit of a deeper view into your code, I see you do a similar thing with the Google convention.

I think it would be quite straightforward for me to implement a similar sphinx convention. I just need a green light from one of the maintainers to Implement it, and I'll start.

[saroad2]

@Nurdok, I would really appreciate your feedback before I go on implementing this.

[sambhav]

From taking a little bit of a deeper view into your code, I see you do a similar thing with the Google convention.

I think it would be quite straightforward for me to implement a similar sphinx convention. I just need a green light from one of the maintainers to Implement it, and I'll start.

We do this for Google as well as numpy style. Before we start implementing it for sphinx style, I would appreciate a link to an official source that defines this guide. Another problem with the current argument and section verification is that in pydocstyle, conventions so far have been a group of violations to check for rather than an actual style guide. As a consequence the checker isn't aware of these conventions and we use some heuristics to determine the style guide of the code base, which leads to false negatives.

I think adding yet another style might make this heuristic very complicated. We already get a lot of false positives and negatives.

So, another thing we need to make a decision on before we do this is whether we should make the checker aware of these conventions.

I am open to this, but I would like to hear @Nurdok and @shacharoo's thoughts on this.

[saroad2]

Thanks for the response!

As for a style guide, here it is.

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.
In that way, you won't get false-positive for convention specific rules.

What do you think?

[sambhav]

Thanks for the response!

As for a style guide, here it is.

This gives a page missing error to me?

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.
In that way, you won't get false-positive for convention specific rules.

What do you think?

I like the idea, the only issue I see is backwards compatibility with existing pydocstyle config and the CLI.

Can you also try to come up with a brief idea on how you would maintain compatibility with existing configurations while adding support for this?

For example, people might have enabled specific error codes but not specified a convention alongside it.

[saroad2]

This gives a page missing error to me?

Sorry, an error with the link. here it is.

Can you also try to come up with a brief idea on how you would maintain compatibility with existing configurations while adding support for this?

I must say that I can't see how this breaks backward compatibility. The code will require a little refactor, but the behavior should stay the same, reducing only false-positives. Can you show me an example of this kind of backward compatibility break?

Edit

The only compatibility break is what you mentioned. One actually could disable a rule when using a convention, but I think it's a good thing.

For example, I want to use the Sphinx convention, but I only want to document :param: and not :type:. while both would have their specific rules that check that they exist, I will use the Sphinx convention and disable the :type: rule.

[Nurdok]

I think it's reasonable to take the --convention flag into consideration (when it's used) instead of the current heuristics to decide how to parse the docstrings. There are a lot of details here (what happens if I enable Google convention and choose a numpy-only error code with --add-select?), so I think the best course of action is to open an issue for this, describing what the exact behavior will be. This won't go to waste as it can later be used for documentation. Any takers?

[saroad2]

I opened the new issue in #482 . You are welcomed to take a look at it :)