Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Fri, 20 Mar 2020 12:59:18 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To:     Federico Vaga <federico.vaga@vaga.pv.it>
Cc:     Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>
Subject: Re: [PATCH] docs: conf.py: avoid thousands of duplicate label
 warning on Sphinx
Message-ID: <20200320125918.5eb5af04@coco.lan>
In-Reply-To: <3508337.2CZTLhteCP@harkonnen>
References: <20200320112122.48244ec4@coco.lan>
        <16f1c270a9077032de379b1cb30dfbb3e3670aee.1584702515.git.mchehab+huawei@kernel.org>
        <3508337.2CZTLhteCP@harkonnen>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Em Fri, 20 Mar 2020 12:24:45 +0100
Federico Vaga <federico.vaga@vaga.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