Re: [PATCH v2 04/33] docs: update recommended Sphinx version to 2.4.4

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 04/33] docs: update recommended Sphinx version to 2.4.4
Date: Tue, 21 Apr 2020 00:12:55 +0200	[thread overview]
Message-ID: <20200421001255.7c7e5065@coco.lan> (raw)
In-Reply-To: <20200420152729.40cb10e1@lwn.net>

Em Mon, 20 Apr 2020 15:27:29 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 14 Apr 2020 18:48:30 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 
> > The Sphinx check script is already smart enough to keep
> > working, with older versions, warning the users that
> > an upgrade is recommended (and explaining how):
> > 
> > 	Sphinx version 1.7.9
> > 	Warning: It is recommended at least Sphinx version 2.4.4.
> > 	Detected OS: Fedora release 31 (Thirty One).
> > 
> > 	To upgrade Sphinx, use:
> > 
> > 		/usr/bin/virtualenv sphinx_2.4.4
> > 		. sphinx_2.4.4/bin/activate
> > 		pip install -r ./Documentation/sphinx/requirements.txt  
> 
> Sigh...that version is all of a month and some old.  I hate to be pushing
> people that hard on the upgrade treadmill.

Yeah, I see the point. 

Please notice that the above will only appear if someone calls "make htmldocs"
and no sphinx-build is found at the patch (or if the version is below the
lower bond - 1.4.x).

> I'm still looking over the set, and will probably apply this, but I think
> we should consider tweaking this before 5.8:
> 
>  - Can we make the warning more explicit that 2.4.4 is needed *if you are
>    generating PDF*?  Most people, I think, don't do that, and can live
>    happily with an older version.

Sure. I can work on a patch for such purpose. 

>  - Perhaps the time has come to raise the lower bound to, say, 1.7?  That
>    might let us get rid of a bit of cruft.

If we move the lower bound, it will start to refuse running "make htmldocs"
with versions below 1.7.

I'm ok on rising the lower limit. Yet, not sure if this is worth.
I mean, last time I checked, html builds fine with older versions.

Ok, if we rise the bar, we may be able to do some cleanups at the
extensions, removing some backward-compatible code. So, I would wait
for some future Sphinx version where the extensions would stop working,
requiring someone to touch them.

Thanks,
Mauro