Re: [PATCH] doc: fix reference to core-api/namespaces.rst

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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