Re: [PATCH 0/2] docs: Programmatically render MAINTAINERS into ReST

Kees Cook
2019-10-01T16:16:45Z

On Tue, Oct 01, 2019 at 12:09:30PM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 1 Oct 2019 08:31:47 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
> > On Tue, 24 Sep 2019 16:02:06 -0700
> > Kees Cook <keescook@chromium.org> wrote:
> >
> > > Commit log from Patch 2 repeated here for cover letter:
> > >
> > > In order to have the MAINTAINERS file visible in the rendered ReST
> > > output, this makes some small changes to the existing MAINTAINERS file
> > > to allow for better machine processing, and adds a new Sphinx directive
> > > "maintainers-include" to perform the rendering.
> >
> > I finally got around to trying this out. After the usual warnings, the
> > build comes to a screeching halt with this:
> >
> > Sphinx parallel build error:
> > UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 8: ordinal not in range(128)
> >
> > For extra fun, the build process simply hangs, requiring a ^C to blow it
> > away. You've managed to get new behavior out of Sphinx that I've not seen
> > before, congratulations :)
> >
> > This almost certainly has to do with the fact that I'm (intentionally)
> > running the Python2 Sphinx build here. Something's not doing unicode that
> > should be.

Given this would be for v5.5, and python2 is EOL in 2 months[1], I don't
think it's unreasonable to deprecate it. Especially considering there
are already explicit "python3" shebangs in existing code in the sphinx/
directory.

[1] https://pythonclock.org/

> > I would suggest that we might just want to repair this before merging this
> > feature. Either that, or we bite the bullet and deprecate the use of
> > Python 2 entirely - something that's probably not too far into our future
> > regardless. Anybody have thoughts on that matter?
>
> I'm almost sure we got this already. If I'm not mistaken, the solution
> is to add the encoding line after shebang. Looking at
> Documentation/sphinx/maintainers_include.py (patch 2/2), the script
> starts with:
>
> #!/usr/bin/env python
> # SPDX-License-Identifier: GPL-2.0
> # -*- coding: utf-8; mode: python -*-
> # pylint: disable=R0903, C0330, R0914, R0912, E0401
>
> But, as I pointed before, the SPDX header at the wrong place is causing the
> crash, as the encoding line should be the second line, not the third one,
> e. g.:
>
> #!/usr/bin/env python
> # -*- coding: utf-8; mode: python -*-
> # SPDX-License-Identifier: GPL-2.0
> # pylint: disable=R0903, C0330, R0914, R0912, E0401
>
> I also suspect that this would happen even with python3, depending on
> how LC_ALL, LANG, ... are set on the distro you use.

Oh that's a delightful bug. :P I haven't been able to reproduce this
failure (maybe all my LANG junk is accidentally correct)?

Jon, if this fixes it for you, should I respin the patches?

--
Kees Cook