[Pulp-dev] Docstring linting
bbouters at redhat.com
Tue Jun 4 14:41:00 UTC 2019
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
On Tue, Jun 4, 2019 at 10:30 AM David Davis <daviddavis at redhat.com> wrote:
> Black doesn't format docstrings so it won't really help us. Flake8 is a
> wrapper for a collection of tools and the one that lints docstrings
> (pydocstyle) 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.
>  https://github.com/python/black/issues/144
>  https://github.com/PyCQA/pydocstyle
> On Tue, Jun 4, 2019 at 10:05 AM Brian Bouterse <bbouters at redhat.com>
>> @mdellweg if we adopt Black broadly, how does that affect your proposal
>> On Tue, May 21, 2019 at 11:50 AM Austin Macdonald <austin at redhat.com>
>>> 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
>>> On Tue, May 21, 2019 at 11:08 AM Matthias Dellweg <dellweg at atix.de>
>>>> 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  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
>>>> 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.
>>>>  https://github.com/pulp/pulpcore/pull/138
>>>> Pulp-dev mailing list
>>>> Pulp-dev at redhat.com
>>> Pulp-dev mailing list
>>> Pulp-dev at redhat.com
>> Pulp-dev mailing list
>> Pulp-dev at redhat.com
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Pulp-dev