[Pulp-dev] Docstring linting

[Dana Walker]

+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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20190606/368b7b73/attachment.htm>