Em Wed, 30 Mar 2022 23:59:05 +0900 Akira Yokosawa <akiyks@xxxxxxxxx> 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