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

[Kees Cook <keescook@chromium.org>]

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