Re: Sphinx pre v3 -- removing support

[Mauro Carvalho Chehab <mchehab@kernel.org>]

Em Fri, 03 Jun 2022 22:05:20 +0300
Jani Nikula <jani.nikula@linux.intel.com> escreveu:

> On Sat, 04 Jun 2022, Akira Yokosawa <akiyks@gmail.com> wrote:
> > [+Cc: Mauro]

Thanks!

> >
> > On Fri, 3 Jun 2022 15:54:33 +0000,
> > Adam Turner wrote:  
> >>>> No releases will be removed from PyPI, but if pre v3 syntax is still
> >>>> used, Sphinx 6.0 would fail to properly parse it.  
> >>   
> >>> And that's the crux of the problem. From kernel POV I'd very much prefer
> >>> not setting an upper bound for the Sphinx version. I think it's
> >>> important to be able to build the documentation using the latest Sphinx,
> >>> and gradually iron out the inevitable quirks that arise.  
> >>   
> >>> However, if you decide to drop support for pre v3 syntax in Sphinx v6,
> >>> and we decide to stick to being able to use pre v3 Sphinx, we can't move
> >>> forward to newer versions until we bump the lower bound for the Sphinx
> >>> version to v3+. (Or we need to hack around Sphinx version differences in
> >>> kernel, but I think that would be best avoided.)  
> >
> > I might not be grasping the full context here, but I think the main script of
> > kernel documentation tool ./scripts/kernel-doc (a perl script) changes its
> > behavior depending on the target Sphinx version.  
> 
> That doesn't change my opinion that it would be best avoided! ;)

Em Fri, 3 Jun 2022 15:27:18 +0000
Adam Turner <aaturnerpython@outlook.com> escreveu:

> I'm referring to removing support for the "c_allow_pre_v3", 
> "c_warn_on_allowed_pre_v3", configuration options [1]_, and the 
> associated support for still parsing the pre v3 syntax in the C 
> domain [2]_. This means that pre v3 syntax in reStructuredText files
> would not work with Sphinx 6 onwards.

If all that it is scheduled for Sphinx 6 is the removal of the
old C domain, this shouldn't be a problem. The kernel-doc has
long gone support to output tags with both pre and post v3 syntaxes.

We also changed the automarkup plugin to allow using v3 C domain
tags when compiling against pre-v3.

Tests required, of course.

-

From my side, there are two points to consider when changing
the minimal release:

- Supporting a version that can build docs 2x faster sounds
  very interesting;
- it would also be interesting to support the native Sphinx
  version that comes with the latest LTS releases,
  As I suspect that bots may benefit from a long-term distros,
  and use the distro-provided signed packages on servers.

  Looking at LTS, what we have is:

	- RHEL 9.0/CentOS 9.0:
	  https://centos.pkgs.org/9-stream/centos-crb-x86_64/python3-sphinx-latex-3.4.3-7.el9.noarch.rpm.html
	  Sphinx 3.4.3
	- Debian 11:
	  Sphinx 3.4.3
	  https://packages.debian.org/bullseye/python3-sphinx
	- Suse 15 SP4:
	  https://scc.suse.com/packages?name=SUSE%20Linux%20Enterprise%20Server&version=15.4&arch=x86_64&query=python3-sphinx&module=
	  Have have both Sphinx 4.2.0 and Sphinx 2.3.1	

  From LTS perspective, it sounds doable to setup the minimal
  version to 3.4, but we would need to adjust the scripts to
  select a different package on Suse, as calling:

	./scripts/sphinx-pre-install --no-virtualenv

  Would recommend installing python3-sphinx package there,
  meaning Sphinx 2.3.1.

So, IMO, we have a couple of alternatives:

1. Change minimal requirement to 2.3:
	- No changes required at sphinx-pre-install's logic;
	- all latest LTS will be supported;
	- pdf will still require a newer version than 2.3.
	- allow "fast builds" with Sphinx < 3;

2. Change minimal requirement to 2.4:
	- no need to check for an specific version for PDF;
	- allow "fast builds" using Sphinx < 3;
	- Changes needed at sphinx-pre-install on Suse logic;

3. Change minimal requirement to 3.4:
	- We can drop backward-compatible logic from kernel-doc
	  and automarkup;
	- all latest LTS will be supported;
	- Changes needed at sphinx-pre-install on Suse logic;
	- No "fast build" suing Sphinx < 3.

On a side note, while Kernel documentation builds with 3.0,
it is not really properly supported, as there are troubles
on C domain there (lots of warnings and broken cross references
are generated there). So, I would avoid setting the minimal 
requirement to 3.0.

Regards,
Mauro