[code-quality] Adoption of doc8

[Stephen Finucane]

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