[Pulp-dev] Docstring linting

[Brian Bouterse]

Great, thanks for the info. Then I'm +1 on adopting the use of pydocstyle
to have great docstrings. AIUI this was the original desire of @mdellweg's
proposal.

On Tue, Jun 4, 2019 at 10:30 AM David Davis <daviddavis at redhat.com> wrote:

> Black doesn't format docstrings[0] so it won't really help us. Flake8 is a
> wrapper for a collection of tools and the one that lints docstrings
> (pydocstyle[1]) can be run independently without flake8. So I think this
> questions around how/if to lint docstrings and whether or not we want to
> use black are independent.
>
> [0] https://github.com/python/black/issues/144
> [1] https://github.com/PyCQA/pydocstyle
>
> David
>
>
> On Tue, Jun 4, 2019 at 10:05 AM Brian Bouterse <bbouters at redhat.com>
> wrote:
>
>> @mdellweg if we adopt Black broadly, how does that affect your proposal
>> here?
>>
>> On Tue, May 21, 2019 at 11:50 AM Austin Macdonald <austin at redhat.com>
>> wrote:
>>
>>> Something else to consider: some docstrings are rendered as user-facing
>>> documentation in the autogenerated REST docs. This means that docstring
>>> linting needs to be ignored for ViewSets. For example, I have a PR open
>>> that alters pulp_file viewset docstrings to contain html, to pass the
>>> linter, we have add docstring exceptions to the flake8 config.
>>>
>>> My initial reaction is that we might be better off keeping the
>>> flake8-docstring package out of pulplift, and we should also remove it from
>>> travis.
>>>
>>>
>>> On Tue, May 21, 2019 at 11:08 AM Matthias Dellweg <dellweg at atix.de>
>>> wrote:
>>>
>>>> tl;dr: Docstring linting is inconsistent across pulp repositories.
>>>> To make it consistent, do we want to enforce it everywhere, and repair
>>>> more than 700 findings?
>>>>
>>>> What started out as a oneliner [0] surfaced as a bigger problem:
>>>>
>>>> Whether flake8 performs linting on docstrings is solely dependent
>>>> (afaik) on the existence of a specific python package
>>>> (flake8-docstring) in the system.
>>>> At the same time, there are repositories (pulpcore,
>>>> pulpcore-plugin, ???) that do not install this package in their ci
>>>> pipeline, as well as repos that do (pulp_deb, pulp_ansible, ???).
>>>> So it is hard to select whether it should be installed in a pulplift
>>>> source box.
>>>> Not installing it means, there are linting errors showing up in
>>>> travis only, however installing it will prevent linting pulpcore
>>>> locally.
>>>> That said, i think we should follow the same linting rules in all
>>>> repositories, and more specific i tend to include docstring linting.
>>>> However there are over 700 findings in pulpcore alone.
>>>>
>>>> [0] https://github.com/pulp/pulpcore/pull/138
>>>> _______________________________________________
>>>> Pulp-dev mailing list
>>>> Pulp-dev at redhat.com
>>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>>
>>> _______________________________________________
>>> Pulp-dev mailing list
>>> Pulp-dev at redhat.com
>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>> _______________________________________________
>> Pulp-dev mailing list
>> Pulp-dev at redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20190604/d739c7c6/attachment.htm>