linux-kernel - Re: [PATCH] docs: conf.py: avoid thousands of duplicate label warning on Sphinx

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20200320125918.5eb5af04@coco.lan>
Date:   Fri, 20 Mar 2020 12:59:18 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Federico Vaga <federico.vaga@...a.pv.it>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>
Subject: Re: [PATCH] docs: conf.py: avoid thousands of duplicate label
 warning on Sphinx

Em Fri, 20 Mar 2020 12:24:45 +0100
Federico Vaga <federico.vaga@...a.pv.it> escreveu:

> On Friday, March 20, 2020 12:12:35 PM CET Mauro Carvalho Chehab wrote:
> > The autosectionlabel extension is nice, as it allows to refer to
> > a section by its name without requiring any extra tag to create
> > a reference name.
> > 
> > However, on its default, it has two serious problems:
> > 
> > 1) the namespace is global. So, two files with different
> >    "introduction" section would create a label with the
> >    same name. This is easily solvable by forcing the extension
> >    to prepend the file name with:
> > 
> > 	autosectionlabel_prefix_document = True
> > 
> > 2) It doesn't work hierarchically. So, if there are two level 1
> >    sessions (let's say, one labeled "open" and another one "ioctl")
> >    and both have a level 2 "synopsis" label, both section 2 will
> >    have the same identical name.
> > 
> >    Currently, there's no way to tell Sphinx to create an
> >    hierarchical reference like:
> > 
> > 		open / synopsis
> > 		ioctl / synopsis
> > 
> >   This causes around 800 warnings. So, the fix should be to
> >   not let autosectionlabel to produce references for anything
> >   that it is not at level one, with:
> > 
> > 	autosectionlabel_maxdepth = 1  
> 
> So, for level 1 headers is fine to use autosectionlabel, but if we want to 
> refer to level 2,3... we have to create labels manually.

Yes.

If we want to use it for other levels, the autosectionlabel extension
would need to be modified to work on an hierarchical way, creating an
unique label that would contain the entire hierarchy, starting from
the filename.

Also, ideally, it should also handle cross-reference locally, searching
first for a reference at the same hierarchical level, then at level - 1
and so on.

I suspect that, even with that, we may still have some troubles, as
right now some files may have explicitly defined a reference like
that, but those would likely be easy to fix.

Thanks,
Mauro