-
Notifications
You must be signed in to change notification settings - Fork 190
[Feature Request] Validate sphinx parameters #478
Comments
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. |
@Nurdok, I would really appreciate your feedback before I go on implementing this. |
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. |
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:
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 What do you think? |
This gives a page missing error to me?
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. |
Sorry, an error with the link. here it is.
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? EditThe 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 |
I think it's reasonable to take the |
I opened the new issue in #482 . You are welcomed to take a look at it :) |
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:
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
.The text was updated successfully, but these errors were encountered: