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

From: Mauro Carvalho Chehab <mchehab@kernel.org>
To: Geert Uytterhoeven <geert@linux-m68k.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
	Markus Heiser <markus.heiser@darmarit.de>,
	Jani Nikula <jani.nikula@intel.com>,
	ksummit <ksummit-discuss@lists.linuxfoundation.org>,
	ksummit@lists.linux.dev
Subject: Re: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be
Date: Tue, 28 Jun 2022 12:01:42 +0100	[thread overview]
Message-ID: <20220628120142.4fe254f7@sal.lan> (raw)
In-Reply-To: <CAMuHMdW_EkQ8pSgJjrZtBXXkitRv2Wq+fP4wCnPmyvaPQO-kxA@mail.gmail.com>

Em Tue, 28 Jun 2022 09:57:29 +0200
Geert Uytterhoeven <geert@linux-m68k.org> escreveu:

> Hi Mauro,
> 
> On Tue, Jun 28, 2022 at 9:43 AM Mauro Carvalho Chehab
> <mchehab@kernel.org> wrote:
> > 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/  
> 
> Ubuntu 20.04 LTS also has 1.8.5.
> Looks like I'll get 4.3.2 after upgrading to 22.04 LTS (which is only
> about two months old).

Yeah, LTS distros are the main reason why the default recommendation is to
install Sphinx via virtualenv/venv.

With RHEL9, SUSE 15 SP4 (plus CenOS and openSUSE Leap versions of them),
plus Ubuntu 22.04, maybe we can change the default to recommend installing
it via distro-provided packages. Yet, Debian bulseye has 2.5.0. Only
bookworm, scheduled for mid 2023, will come with Sphinx > 2.

Regards,
Mauro