[Pulp-dev] Docstring linting

[Matthias Dellweg]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20190604/20375bd9/attachment.sig>