Re: [PATCH] docs: sphinx/requirements: Limit jinja2<3.1

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

Em Wed, 30 Mar 2022 23:59:05 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> Hi Mauro,
> 
> On Wed, 30 Mar 2022 02:25:34 +0200,
> Mauro Carvalho Chehab wrote:
> [...]
> > We need to verify both PDF and html generation, though, as I remember
> > that some 4.x versions had/(have?) issues with the C domain and duplicate
> > symbols detection.  
> 
> Can you elaborate on the issue you observed?
> In which document did you see it?

Sorry, it was on Sphinx 3.x, although the most complete fix got
merged on 4.0, I guess. This patch is related to it:

	b34b86d7a418 ("docs: conf.py: fix c:function support with Sphinx 3.x")

Basically, the Sphinx maintainer for the C domain rewrote the code,
causing all references generated by kernel-doc to be broken, and
almost all references at the media docs as well. Before the changes,
there were just one domain for C code references, used for functions,
structs, enums, etc. After the change, each one requires a different
tag. The kerneldoc script has gained support for Sphinx version when
such issue was addressed.

Another consequence of such change is that you can't have more than
one "read()" function inside the entire Kernel. While this makes
sense on userspace, It doesn't at Kernelspace, as different subsystems
may handle read/write/ioctl/... syscalls on their particular ways.
So, building docs were causing warnings about duplicated symbols.

There were some changes that went on 4.x to fix it, when 
".. c:namespace::" got merged. I don't remember when it was added.

> Verification of generated HTML and PDF can be hard.
> 
> Different Sphinx might generate slightly different .html or .tex
> files with no visible effect in the final rendering.  Hmm...

That was not the case on that time. We had to stick to Sphinx up to
version 2.4 for a couple of Kernel release cycles, in order to fix, as the
changes weren't trivial.

> Do you have an idea for automated regression testing?

Except for doing periodic html and pdf builds and reporting build errors,
no.

For html, perhaps some regression testing could be done by using pandoc
to convert html back into ReST (or to some other format) and compare if the
output from the same source with different Sphinx versions are identical 
(or similar enough). On such case, I would get rid of using read the docs
style, using the simplest possible one. That's easier said than done, though,
as such conversion could produce errors due to problems on pandoc - or some
minor differences - So, whomever would be running such tests would likely
need to add something in order to handle similar but different outputs and
exclude false-positives.

> 
> > 
> > Also, it could be worth to check the build time with 2.4.4 and with
> > whatever newer version we stick.  
> 
> I agree. I'll see what I can do.
> 
>         Thanks, Akira
> 
> >   
> >> So I'll just fast-track this
> >> patch in; dropping it into the stable updates probably makes sense too.  
> > 
> > Agreed.
> > 
> > Thanks,
> > Mauro  



Thanks,
Mauro