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 11:21:22 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To:     Federico Vaga <federico.vaga@vaga.pv.it>
Cc:     Jonathan Corbet <corbet@lwn.net>, linux-kernel@vger.kernel.org,
        linux-doc@vger.kernel.org
Subject: Re: [PATCH] doc: fix reference to core-api/namespaces.rst
Message-ID: <20200320112122.48244ec4@coco.lan>
In-Reply-To: <2008227.4siv4ILC15@harkonnen>
References: <20191122115337.1541-1-federico.vaga@vaga.pv.it>
        <20191122103437.59fda273@lwn.net>
        <2008227.4siv4ILC15@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 Sun, 24 Nov 2019 18:02:02 +0100
Federico Vaga <federico.vaga@vaga.pv.it> escreveu:

> > diff --git a/Documentation/conf.py b/Documentation/conf.py
> > index 3c7bdf4cd31f..fa2bfcd6df1d 100644
> > --- a/Documentation/conf.py
> > +++ b/Documentation/conf.py
> > @@ -38,7 +38,7 @@ needs_sphinx = '1.3'
> >  # ones.
> >  extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
> >                'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
> > -              'maintainers_include']
> > +              'maintainers_include', 'sphinx.ext.autosectionlabel' ]
> > 

Testing today's linux-next branch. This extension caused *lots* of
warnings like this:

	Documentation/driver-api/uio-howto.rst:12: WARNING: duplicate label translations, other instance in Documentation/index.rst

The thing is that, by default, autosectionlabel uses a global namespace,
with cause lots of troubles with sections like "introduction". So, it
needs to be ensured that no duplication will happen.

Btw, I tried to setup this:

	diff --git a/Documentation/conf.py b/Documentation/conf.py
	index fa2bfcd6df1d..7eaadde98a86 100644
	--- a/Documentation/conf.py
	+++ b/Documentation/conf.py
	@@ -40,6 +40,9 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
	               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
	               'maintainers_include', 'sphinx.ext.autosectionlabel' ]
	 
	+# Avoid lots of warnings with autosectionlabel extension
	+autosectionlabel_prefix_document = True
	+
	 # The name of the math extension changed on Sphinx 1.4
	 if (major == 1 and minor > 3) or (major > 1):
	     extensions.append("sphinx.ext.imgmath")
	
But I still get lots of duplicated section labels inside the same file,
like this one (757 warnings):

	docs/Documentation/driver-api/parport-lowlevel.rst:815: WARNING: duplicate label driver-api/parport-lowlevel:description, other instance in Documentation/driver-api/parport-lowlevel.rst

There we have things that are similar to man pages, like this:

	parport_register_driver - register a device driver with parport
	---------------------------------------------------------------

	SYNOPSIS
	^^^^^^^^
...

	parport_unregister_driver - tell parport to forget about this driver
	--------------------------------------------------------------------

	SYNOPSIS
	^^^^^^^^

A solution would be to split all the files that are hitting this, but
I suspect that this is too much effort for too less benefit.

I would instead just revert this patch and fix it by adding a normal
explicit reference.

Another alternative would be to patch the Sphinx extension to make it
handle references on an hierarchical way, e. g. the above references
should be, instead of just "synopsis":

	parport-lowlevel / parport_register_driver - register a device driver with parport / synopsis
	parport-lowlevel / parport_unregister_driver - tell parport to forget about this driver / synopsis

Thanks,
Mauro