Re: Linux 5.10-rc2 (docs build)

[Mauro Carvalho Chehab]

Em Mon, 2 Nov 2020 12:41:53 -0800
Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu:

> On 11/2/20 12:35 PM, Mauro Carvalho Chehab wrote:
> > Em Mon, 2 Nov 2020 11:23:25 -0800
> > Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu:
> >   
> >> On 11/2/20 8:59 AM, Mauro Carvalho Chehab wrote:  
> >>> Em Mon, 2 Nov 2020 08:02:34 -0800
> >>> Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu:
> >>>     
> >>>> On 11/2/20 12:33 AM, Mauro Carvalho Chehab wrote:    
> >>>>> Em Mon, 2 Nov 2020 08:58:41 +0100
> >>>>> Mauro Carvalho Chehab <mchehab@xxxxxxxxxx> escreveu:
> >>>>>       
> >>>>>> Hi Randy,
> >>>>>>
> >>>>>> Em Sun, 1 Nov 2020 16:01:54 -0800
> >>>>>> Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu:
> >>>>>>      
> >>>>>>> Something broke the docs build (SEVERE):
> >>>>>>>
> >>>>>>>
> >>>>>>> Sphinx parallel build error:
> >>>>>>> docutils.utils.SystemMessage: /home/rdunlap/lnx/lnx-510-rc2/Documentation/ABI/testing/sysfs-bus-rapidio:2: (SEVERE/4) Title level inconsistent:
> >>>>>>>
> >>>>>>> Attributes Common for All RapidIO Devices
> >>>>>>> -----------------------------------------
> >>>>>>>
> >>>>>>>      
> >>>>>>
> >>>>>> On what tree did you notice this? Linux-next or upstream?      
> >>>>
> >>>> See $Subject:  5.10-rc2
> >>>>
> >>>>    
> >>>>> Also: on what Sphinx version are you getting it? I'm not
> >>>>> able to reproduce the issue here, neither with Sphinx 2.4.4
> >>>>> nor with Sphinx 3.2.1.      
> >>>>
> >>>> That could be one source of the problem:  ;)
> >>>>
> >>>> from my docs build:
> >>>>
> >>>> Sphinx version: 1.7.6
> >>>> Warning: It is recommended at least Sphinx version 1.7.9.
> >>>>          If you want pdf, you need at least 2.4.4.    
> >>>
> >>> Could be... From 1.7.6 to 1.7.9, there were bug fixes ;-)
> >>>
> >>> Also, on Sphinx, they stop maintaining old versions once newer
> >>> stable ones are launched. So, any bug on 1.7.x (up to 3.2.x) will
> >>> remain unfixed[1].
> >>>
> >>> In any case, could you please check if this patch solves the
> >>> issue?
> >>>
> >>> 	https://lore.kernel.org/lkml/6c62ef5c01d39dee8d891f8390c816d2a889670a.1604312590.git.mchehab+huawei@xxxxxxxxxx/    
> >>
> >> Nope, sorry, with that patch applied to v5.10-rc2, I get:
> >>
> >> reading sources... [ 93%] userspace-api/media/v4l/pixfmt-y8i .. userspace-api/media/v4l/vidioc-querybuf
> >> reading sources... [ 96%] userspace-api/media/v4l/vidioc-querycap .. vm/transhuge
> >> reading sources... [100%] vm/unevictable-lru .. xtensa/mmu
> >>
> >> waiting for workers...
> >>
> >> {hangs; enter ^C}
> >>
> >> Sphinx parallel build error:
> >> docutils.utils.SystemMessage: /home/rdunlap/lnx/lnx-510-rc2/Documentation/ABI/testing/sysfs-class-led-trigger-pattern.orig:16: (SEVERE/4) Unexpected section title.  
> > 
> > Hmm...
> > 	sysfs-class-led-trigger-pattern.orig
> > 
> > That doesn't sound right! It seems you have a backup of an old file
> > there ;-)  
> 
> Ha! I didn't even notice that.  :(
> 
> Anyway, it's not illegal to have such files, so Documentation builds
> should ignore them (IMO).

I agree that it should ignore, but unfortunately Sphinx works with
directories and it tries to use all files there that matches the 
expected extension, and not only the ones that are inside the index 
files.

So, if you want to keep a backup of an older version, I
suggest to rename the file extension.

> > -
> > 
> > In order to double-check, I tested it here with:
> > 
> > 	$ /usr/bin/python3 -m venv sphinx_1.7.6
> > 	$ pip install docutils sphinx_rtd_theme Sphinx==1.7.6
> > 	$ pip install docutils==0.15 sphinx_rtd_theme Sphinx==1.7.6
> > 
> > 
> > And then built the docs with:
> > 
> > 	$ time make O="sphinx1.7" SPHINXOPTS="-w new_warnings --no-color" cleandocs htmldocs
> > 
> > Everything build fine (except for a huge amount of warnings that seem
> > to indicate some bug at the cross-reference logic with 1.7.6).  
> 
> OK, I'll wait to see how things are in -rc2 or so.
> 
> thanks.

Ok.

Thanks,
Mauro