[Pulp-dev] Docstring linting

Daniel Alley dalley at redhat.com
Fri Jun 7 04:28:24 UTC 2019


+1 to create a PUP

(-0 to actually adopting it. No particularly strong feelings though.)

On Thu, Jun 6, 2019 at 4:21 PM Dana Walker <dawalker at redhat.com> wrote:

> +1
>
> Dana Walker
>
> She / Her / Hers
>
> Software Engineer, Pulp Project
>
> Red Hat <https://www.redhat.com>
>
> dawalker at redhat.com
> <https://www.redhat.com>
>
>
>
> On Thu, Jun 6, 2019 at 1:34 PM Brian Bouterse <bbouters at redhat.com> wrote:
>
>>
>>
>> On Wed, Jun 5, 2019 at 4:39 PM David Davis <daviddavis at redhat.com> wrote:
>>
>>> Given the generally favorable response so far to using black, I was
>>> thinking of writing up a PUP to add black into pulpcore, pulpcore-plugin,
>>> pulp_file, and pulp_template. And to make it the recommended format for
>>> plugins. I can include docstring linting in that PUP as well.
>>>
>> +1 this sounds good to me.
>>
>>
>>> David
>>>
>>>
>>> On Wed, Jun 5, 2019 at 9:25 AM Brian Bouterse <bbouters at redhat.com>
>>> wrote:
>>>
>>>> I'm +1 on merging the proposals; it just seems easier. If not, I'd
>>>> bring it as a followup proposal because I see value in this docstring
>>>> linting.
>>>>
>>>> On Tue, Jun 4, 2019 at 11:00 AM Matthias Dellweg <dellweg at atix.de>
>>>> wrote:
>>>>
>>>>> The core problem this proposal tried to counteract is, just like the
>>>>> one with black, inconsistency across different repositories in the pulp
>>>>> namespace. Some lint docstrings and others don't even adhere to the
>>>>> linted style. Given the architecture of flake8 this leads to strange
>>>>> effects when you try to lint your code in the pulplift boxes.
>>>>> So what i really am aiming for here is consistency wrt to docstrings
>>>>> and docstring linting. This sounds like beeing almost the same goal as
>>>>> the black proposal. It would be fine for me to even merge those
>>>>> proposals.
>>>>>
>>>>> Matthias
>>>>>
>>>>> On Tue, 4 Jun 2019 10:29:58 -0400
>>>>> 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
>>>>>
>>>> _______________________________________________
>> 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/20190607/eb928cbb/attachment.htm>


More information about the Pulp-dev mailing list