Re: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be

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

Em Mon, 27 Jun 2022 09:27:54 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Markus Heiser <markus.heiser@darmarit.de> writes:
> 
> > IMO It is unnecessary that the build-chain must run on all
> > platforms and with all distributions.
> >
> > Who observes the Sphinx-doc & docutils development since (>15)
> > years is aware that with various (old) Sphinx-doc & docutils
> > versions no stable results can be produced, not without
> > complicating the build-chain.  And this is exactly the situation
> > we are facing today.
> >
> > The build chain of documentation has nothing to do with kernel
> > development (at least in my opinion) and should be decoupled from it:
> > maintaining one defined build environment is enough work ... this
> > becomes especially clear if you (as Jani recommends) rely more on
> > sphinx-modules and widely used tools.  
> 
> The counterargument to this is that we want as many developers as
> possible to be able to build the docs and contribute to them.  We can't
> complain that developers have broken the docs build if we don't do what
> we can to help them do the build themselves.

Agreed.

> One of our longstanding contributors is on Sphinx 1.8.5:
> 
>   https://lwn.net/ml/linux-doc/4c403239-3c71-4ab9-2168-f7e9d77008b2%40infradead.org/

If he migrates to Leap 15.4, he'll either get 2.3.1 (default package)
or 4.2.0 (alternative package):

	https://download.opensuse.org/distribution/leap/15.4/repo/oss/noarch/python3-Sphinx-2.3.1-150400.1.7.noarch.rpm
	https://download.opensuse.org/distribution/leap/15.4/repo/oss/noarch/python3-Sphinx_4_2_0-4.2.0-150400.11.6.noarch.rpm

> I would like to narrow our range of supported versions, but I really
> don't want to cut people out.
> 
> The real question, perhaps, is whether requiring people to set up a
> virtualenv to run a supported version would be too much.  It's something
> I worry about.

Installing distro-specific packages likely covers a broader group of
developers than requiring virtualenv/venv.

However, if we decide to move on, removing the version-dependent
hacks from the build system, it would mean that the minimal version
would be 3.1.0. On such case, there won't be Sphinx packages on some
LTS distros. Developers using such distros will be forced to use 
virtualenv/venv.

In any case, the script which checks if sphinx-build runs can recommend
either way. Yet, as the current default is venv, tests are needed to check
if it recommending python3-sphinx packages still work on all supported
distros.

Such script could also be changed to detect if the distro has a
native package >= 3.1.0, recommending it by default, falling back to
virtualenv/venv otherwise.

Regards,
Mauro