[code-quality] Adoption of doc8

[Ian Stapleton Cordasco]

On Thu, Jul 18, 2019 at 8:04 AM Stephen Finucane <stephen at that.guru> wrote:
>
> On Thu, 2019-07-18 at 07:36 -0500, Ian Stapleton Cordasco wrote:
> > I'm not sure. Bandit, however, completed the transition a few years
> > ago. I suspect there are clues in Gerrit and on the mailing list
> > archives here and there. Once y'all have a GitHub repository you'd
> > like to move over. You can either add me to it so I can move it into
> > the org or I can make the teams, make y'all moderators and I _think_
> > that will give you the ability to move it yourselves.
>
> Sure, I'll get a move on with this now, starting with a mail to
> openstack-discuss (just sent) and a patch based on [1]. Instead of
> moving a repo across though, perhaps you could just create an empty
> 'pycqa/doc8' repo that we can populate, adding us an admins in the
> process? This means we don't have to work through moving things from
> the OpenStack organization on GitHub or having the "forked from"
> metadata on the repo. If there's an empty repo, I can just push
> everything to that.


Sure thing. That's done. I've invited Sorin to the organization but I
don't know your GitHub username to add you, Stephen.

> Stephen
>
> [1] https://review.opendev.org/#/c/564453/
>
> > On Tue, Jul 16, 2019 at 10:44 AM Stephen Finucane <stephen at that.guru>
> > wrote:
> > > On Sat, 2019-07-13 at 12:26 -0500, Ian Stapleton Cordasco wrote:
> > > > On Sat, Jul 13, 2019 at 12:23 PM Stephen Finucane <
> > > > stephen at that.guru> wrote:
> > > > > Hi,
> > > > >
> > > > > I'd like to explore the idea of adopting the 'doc8' tool within
> > > > > the
> > > > > PyCQA organization. For anyone not familiar with the tool,
> > > > > 'doc8'
> > > > > markets itself as "an opinionated style checker for rst (with
> > > > > basic
> > > > > support for plain text) styles of documentation." It's
> > > > > currently
> > > > > maintained within the OpenStack community but there have been
> > > > > some
> > > > > valid concerns raised recently regarding the health of the
> > > > > 'doc8' tool
> > > > > [1]. While it is extensively used within OpenStack (and outside
> > > > > it too,
> > > > > fwiw), it's very much secondary to the core goal of OpenStack
> > > > > itself,
> > > > > which probably explains the lack of attention it's received
> > > > > over the
> > > > > last few years.
> > > > >
> > > > > While 'doc8' is not a checker for Python code itself, it is
> > > > > Python-
> > > > > based, is a "quality tool", and rST+docutils/Sphinx remains the
> > > > > documentation tool of choice for the Python community. For this
> > > > > reason,
> > > > > I think PyCQA might be a good fit as a parent organization. The
> > > > > other
> > > > > possible parent organizations I've been looking at are sphinx-
> > > > > doc/sphinx-contrib and docutils, but doc8 isn't actually
> > > > > Sphinx-based,
> > > > > which kind of rules out the former, while the docutils
> > > > > community are
> > > > > _still_ insisting on Sourceforge and Subversion, ruling them
> > > > > out :(
> > > > >
> > > > > Does anyone else think PyCQA might possibly make a good fit for
> > > > > 'doc8'?
> > > > > If so, I'll raise the idea formally within OpenStack and start
> > > > > on the
> > > > > paperwork to move things across. If not, I'd welcome other
> > > > > ideas for
> > > > > where this useful project could live.
> > > > >
> > > > > Stephen
> > > > >
> > > > > [1]
> > > > > http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007669.html
> > > >
> > > > I thiink it's definitely a fit given its focus. I don't know that
> > > > there's anyone in the PyCQA, however, who has the cycles to
> > > > maintain
> > > > it. Would you and Sorin be willing to maintain it inside the
> > > > PyCQA?
> > > > I'd be happy to set things up so that you both could add more
> > > > maintainers easily.
> > >
> > > Yeah, that would be the expectation, though I would hope that some
> > > other interested parties might eventually discover the project and
> > > pitch in, of course (wishful thinking, perhaps :)).
> > >
> > > What are the next steps?
> > >
> > > Stephen
> > >
> > > > Cheers,
> > > > Ian
>