Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Add an initial Google convention #357
Sources for docstring convention:
Rationale for exclusions of errors:
Adds the following violations:
Thanks for submitting a PR!
Please make sure to check for the following items:
Please don't get discouraged as it may take a while to get a review.
Sources for docstring convention: [Google Style Guide](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) and [Napoleon Google Style Guide](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) Rationale for exclusions of errors: D203: Multiple examples with class docstrings without blank line. D204: Same as above. D213: All multiline summaries start immediately after the triple quotes. D215: N/A no underlines. D400: First line can end with "period, question mark, or exclamation point". D401: Style guide explicitly says not to use imperative mood and use descriptive mood. D404: Clearly allowed WRT to the above. There is also an example using "This". D406: Section names end with a colon. D407: N/A no underlines. D408: N/A no underlines. D409: N/A no underlines.
While writing this patch I am coming to the realization that conventions, as they are currently defined in pydocstyle, might lead to too complex code. Rather than having them as a list of errors to ignore it makes more sense for each of them to define a certain set of errors instead, following which the checkers should be segregated to match the conventions.
But this might be a backwards incompatible change especially since
I will meanwhile continue to write the checkers given the current constraints of conventions and ignores.
@sigmavirus24 I think Pydocstyle shouldn't become a plug-and-play system for running convention checkers. Code should comply with the conventions we check in it, not manipulate it to fit their specific needs.
@samj1912 - I'll try to make some time this weekend to take a look at it. Thanks for contributing!
Why? I think PEP-257, numpy and the Google convention are popular enough and have a big enough traction in their own fields to merit enforcement. But I definitely don't want to encourage folks to create their own conventions. If I could eliminate all but one convention, I would :)
Pydocstyle has the option to enable and disable violations to support a gradual ramp up to full conformance and I accept that some codebases will never fully conform (and some conformance may be better than none). But I'm on the side of having an opinionated linter - that only helps you if you're trying to stick to a known convention. If some developers somewhere want to support a new convention other than the ones mentioned here, I sincerely hope they fail and adopt PEP-257 instead
What if I told you, by allowing plug-able conventions, you could. ;)
There are code-bases much older than PEP-257 and older than this tool. Those code-bases probably have conventions they'd like to enforce but have to do manually in a completely error-prone way and updating them is toilsome and a potentially ridiculous amount of work. I, for one, really don't think that they should have to fork this tool in order to gain the benefits of automated docstring style enforcement.
Only having 1 (or 2, or 3, ... or 5) standards works well enough when it's considered very early on (see also golint, rust-lang's doc format, etc.) but for Python we don't have that luxury and saying "I'll only support these hand-waving number of conventions because they're the most popular" comes across really poorly to the rest of the Python world.