Add Google docstring convention

[pmatos]

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]

@Nurdok , How about 'dem entry points? 😄

[anotherbugmaster]

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]

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

[shacharoo]

@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]

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]

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

• Quite comprehensive specification for Numpy style; no specification at all for Google style (besides the couple of examples in the Google Python Style Guide)
• Correct Pycharm tooltips for Numpy style; Everything more complex than primitive types aren't handled with Google Style
• Numpy style is more compact horizontally; Google Style is more compact vertically
• Numpy style has dashlines; Google Styles has tabs (which are subjectively more convenient)

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]

@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]

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

[ermik]

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

[gunny-probably]

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

[Nurdok]

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

[dickreuter]

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

[demus]

Checking in to see if anyone is working on this?

[Nurdok]

@demus not that I'm aware.

[demus]

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

[ermik]

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

[eterna2]

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

[dickreuter]

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 ***@***.***> 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]

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

[sambhav]

Since the actual convention is pretty loosely defined, I started a PR draft here -
#357
based on my observations from the sources I have provided.

[demus]

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]

I am done with a basic implementation in #357

Will continue to add features over time.

[dickreuter]

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

…

On 21 Apr 2019, at 20:29, Sambhav Kothari ***@***.***> 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]

@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]

@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 c028849

[sambhav]

@Nurdok I guess this can now be closed?