search

PyCQA / pydocstyle

docstring style checker
http://pydocstyle.org
MIT License
1.11k stars 189 forks source link

Add Google docstring convention #275

Closed pmatos closed 5 years ago

pmatos commented 7 years ago

There are lots of projects out there using the google docstring convention. Given numpy has been recently added under #129, this is a request to add the google docstring convention.

Comparison between the two can be found here.

shacharoo commented 7 years ago

@Nurdok , How about 'dem entry points? 😄

anotherbugmaster commented 7 years ago

Are there really much projects using Google style? I couldn't find even 5. It's poorly documented and doesn't have syntax for complex types such as List[Tuple(int, float)].

anotherbugmaster commented 7 years ago

What's bothers me more is that current style checker makes no distinction between Numpy and Google style docstrings.

shacharoo commented 7 years ago

@anotherbugmaster could you elaborate? As I see it, pydocstyle recognizes a set of errors. The so called "conventions" are only presets that define which are selected and which are ignored. Google and numpy conventions are pretty much the same, it's not up to pydocstyle to recognize which is which.

DanCardin commented 7 years ago

Yea I was looking for google style also. It would be nice if it would enforce rules like google section rules ending in ":" (best i can get currently is disabling 406 and 407), and e.g. Args, Raises, and Returns section bodys being indented, and each line being formatted like

Args:
    param (optional type): description
anotherbugmaster commented 7 years ago

@shacharoo They look similar, but definitely not the same. Here are the main differences:

So, if one wants a correct rendering of type annotations for Python 2, she should stick with Numpy Style. Otherwise, of course, it doesn't really matter.

In my case I really want to have those types and Google Style should be prohibited.

shacharoo commented 7 years ago

@anotherbugmaster yes, I know they are not the same convention 😄 You wrote: "What's bothers me more is that current style checker makes no distinction between Numpy and Google style docstrings.". What do you mean by that? pep257 and numpy are the only conventions supported now. If you'll run pydocstyle on a file that has Google docstring conventions it will definitely return errors.

anotherbugmaster commented 7 years ago

Nope, at least in some cases it won't. I'll provide you with an example later.

ermik commented 6 years ago

Is there interest in adding Google's convention to pydocstyle? Getting it well-documented might be something I can help with.

gunny-probably commented 6 years ago

Is this a open source issue? Might be down to put in some hours to support Google's convention as well @ermik

Nurdok commented 6 years ago

@gunny-probably Pydocstyle is indeed open source. PRs welcome! :smile:

dickreuter commented 6 years ago

Currently there is no error if the input arguments are not listed at all in the docstring or if the format is different.

demus commented 6 years ago

Checking in to see if anyone is working on this?

Nurdok commented 6 years ago

@demus not that I'm aware.

demus commented 6 years ago

Started working on it here: https://github.com/demus/pydocstyle/tree/google-style-docstrings

ermik commented 6 years ago

Jumping back in after a long time in a lot of projects. @demus I'd be glad to take part somehow.

eterna2 commented 5 years ago

@demus any progress so far? Would be nice to have google style docstring supported.

dickreuter commented 5 years ago

Especially if it would enforce that all parameters of a function are mentioned in the docstring. That’s probably the most required feature.

On 11 Apr 2019, at 04:20, Eterna2 notifications@github.com wrote:

@demus any progress so far? Would be nice to have google style docstring supported.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

sambhav commented 5 years ago

If no one else is working on this actively, I would like to take this up.

sambhav commented 5 years ago

Since the actual convention is pretty loosely defined, I started a PR draft here - https://github.com/PyCQA/pydocstyle/pull/357 based on my observations from the sources I have provided.

demus commented 5 years ago

My bad, I haven't made progress on this.

I learned that a large percentage of the "section" test code needs to be refactored since it is specific to the numpy style. This was a larger undertaking than I had time for at the time.

sambhav commented 5 years ago

I am done with a basic implementation in https://github.com/PyCQA/pydocstyle/pull/357

Will continue to add features over time.

dickreuter commented 5 years ago

Is it possible to assert that all function parameters are mentioned in the docstring?

On 21 Apr 2019, at 20:29, Sambhav Kothari notifications@github.com wrote:

I am done with a basic implementation in #357

Will continue to add features over time.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

sambhav commented 5 years ago

@dickreuter that is on my TODO list, but the current PR is getting big and I don't want to add more features to it.

I will create those PRs once the current one is reviewed.

sambhav commented 5 years ago

@dickreuter I was able to squeeze in the function arg check with surprisingly less amount of code. So I added support for it (D417) See https://github.com/PyCQA/pydocstyle/pull/357/commits/c02884919e3f3708a1343443b52cb9b69434663c

sambhav commented 5 years ago

@Nurdok I guess this can now be closed?