[Pulp-dev] Docstring linting

[David Davis]

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/44121d7b/attachment.htm>