[Pulp-dev] Docstring linting

[Austin Macdonald]

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