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

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: <20200320112122.48244ec4@coco.lan>
Date:   Fri, 20 Mar 2020 11:21:22 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Federico Vaga <federico.vaga@...a.pv.it>
Cc:     Jonathan Corbet <corbet@....net>, linux-kernel@...r.kernel.org,
        linux-doc@...r.kernel.org
Subject: Re: [PATCH] doc: fix reference to core-api/namespaces.rst

Em Sun, 24 Nov 2019 18:02:02 +0100
Federico Vaga <federico.vaga@...a.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