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

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

[Federico Vaga]

This patch:

commit fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")

forgot to update the document kernel-hacking/hacking.rst.

In addition to the fix the path now is a cross-reference to the document.

Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
 Documentation/core-api/symbol-namespaces.rst | 2 ++
 Documentation/kernel-hacking/hacking.rst     | 4 ++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/core-api/symbol-namespaces.rst b/Documentation/core-api/symbol-namespaces.rst
index 982ed7b568ac..6791f8a5d726 100644
--- a/Documentation/core-api/symbol-namespaces.rst
+++ b/Documentation/core-api/symbol-namespaces.rst
@@ -1,3 +1,5 @@
+.. _core-api-namespace:
+
 =================
 Symbol Namespaces
 =================
diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst
index a3ddb213a5e1..107c8fd3f6c0 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -601,7 +601,7 @@ Defined in ``include/linux/export.h``
 
 This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol
 namespace. Symbol Namespaces are documented in
-``Documentation/kbuild/namespaces.rst``.
+:ref:`Documentation/core-api/symbol-namespaces.rst <core-api-namespace>`.
 
 :c:func:`EXPORT_SYMBOL_NS_GPL()`
 --------------------------------
@@ -610,7 +610,7 @@ Defined in ``include/linux/export.h``
 
 This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol
 namespace. Symbol Namespaces are documented in
-``Documentation/kbuild/namespaces.rst``.
+:ref:`Documentation/core-api/symbol-namespaces.rst <core-api-namespace>`.
 
 Routines and Conventions
 ========================
-- 
2.21.0

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

[Jonathan Corbet]

On Fri, 22 Nov 2019 12:53:37 +0100
Federico Vaga <federico.vaga@vaga.pv.it> wrote:

> This patch:
> 
> commit fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
> 
> forgot to update the document kernel-hacking/hacking.rst.
> 
> In addition to the fix the path now is a cross-reference to the document.
> 
> Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
> ---
>  Documentation/core-api/symbol-namespaces.rst | 2 ++
>  Documentation/kernel-hacking/hacking.rst     | 4 ++--
>  2 files changed, 4 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/core-api/symbol-namespaces.rst b/Documentation/core-api/symbol-namespaces.rst
> index 982ed7b568ac..6791f8a5d726 100644
> --- a/Documentation/core-api/symbol-namespaces.rst
> +++ b/Documentation/core-api/symbol-namespaces.rst
> @@ -1,3 +1,5 @@
> +.. _core-api-namespace:
> +

So I've been wondering for a bit why we don't use section headers as
targets more often rather than adding all these tags.  Perhaps it's because
we never enabled that extension? What do you think of this as an
alternative fix? (Probably before committing this I would split into two,
since enabling the extension merits its own patch).

Thanks,

jon

From b5ca7304e1a7f67717acff2a7bf50f56d387afdd Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <corbet@lwn.net>
Date: Fri, 22 Nov 2019 10:30:30 -0700
Subject: [PATCH] docs: fix reference to core-api/namespaces.rst

Fix a couple of dangling links to core-api/namespaces.rst by turning them
into proper references.  Enable the autosection extension (available since
Sphinx 1.4) to make this work.

Co-developed-by: Federico Vaga <federico.vaga@vaga.pv.it>
Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py                    | 2 +-
 Documentation/kernel-hacking/hacking.rst | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

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' ]
 
 # The name of the math extension changed on Sphinx 1.4
 if (major == 1 and minor > 3) or (major > 1):
diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst
index a3ddb213a5e1..d707a0a61cc9 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -601,7 +601,7 @@ Defined in ``include/linux/export.h``
 
 This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol
 namespace. Symbol Namespaces are documented in
-``Documentation/kbuild/namespaces.rst``.
+:ref:`Documentation/core-api/symbol-namespaces.rst <Symbol Namespaces>`
 
 :c:func:`EXPORT_SYMBOL_NS_GPL()`
 --------------------------------
@@ -610,7 +610,7 @@ Defined in ``include/linux/export.h``
 
 This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol
 namespace. Symbol Namespaces are documented in
-``Documentation/kbuild/namespaces.rst``.
+:ref:`Documentation/core-api/symbol-namespaces.rst <Symbol Namespaces>`
 
 Routines and Conventions
 ========================
-- 
2.21.0

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

[Federico Vaga]

On Friday, November 22, 2019 6:34:37 PM CET Jonathan Corbet wrote:
> On Fri, 22 Nov 2019 12:53:37 +0100
> 
> Federico Vaga <federico.vaga@vaga.pv.it> wrote:
> > This patch:
> > 
> > commit fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
> > 
> > forgot to update the document kernel-hacking/hacking.rst.
> > 
> > In addition to the fix the path now is a cross-reference to the document.
> > 
> > Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
> > ---
> > 
> >  Documentation/core-api/symbol-namespaces.rst | 2 ++
> >  Documentation/kernel-hacking/hacking.rst     | 4 ++--
> >  2 files changed, 4 insertions(+), 2 deletions(-)
> > 
> > diff --git a/Documentation/core-api/symbol-namespaces.rst
> > b/Documentation/core-api/symbol-namespaces.rst index
> > 982ed7b568ac..6791f8a5d726 100644
> > --- a/Documentation/core-api/symbol-namespaces.rst
> > +++ b/Documentation/core-api/symbol-namespaces.rst
> > @@ -1,3 +1,5 @@
> > +.. _core-api-namespace:
> > +
> 
> So I've been wondering for a bit why we don't use section headers as
> targets more often rather than adding all these tags.  Perhaps it's because
> we never enabled that extension? What do you think of this as an
> alternative fix? (Probably before committing this I would split into two,
> since enabling the extension merits its own patch).

I take this occasion to express my opinion, even if it is not a strong 
opinion, I am fine with your solution.

A tag should be always unique (a duplicated tag is an error), so a reference 
to it can't (shouldn't) be wrong. A section header could be repeated when it 
is, let's say, too generic (e.g. "Introduction" is a legitimate section in any 
document). Then we can have both:
- a document title is, in general, unique so it is not a problem to use it as 
targets
- a document sub-section could collide with others so it is preferable an 
unique tag.

> 
> Thanks,
> 
> jon
> 
> From b5ca7304e1a7f67717acff2a7bf50f56d387afdd Mon Sep 17 00:00:00 2001
> From: Jonathan Corbet <corbet@lwn.net>
> Date: Fri, 22 Nov 2019 10:30:30 -0700
> Subject: [PATCH] docs: fix reference to core-api/namespaces.rst
> 
> Fix a couple of dangling links to core-api/namespaces.rst by turning them
> into proper references.  Enable the autosection extension (available since
> Sphinx 1.4) to make this work.
> 
> Co-developed-by: Federico Vaga <federico.vaga@vaga.pv.it>
> Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/conf.py                    | 2 +-
>  Documentation/kernel-hacking/hacking.rst | 4 ++--
>  2 files changed, 3 insertions(+), 3 deletions(-)
> 
> 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' ]
> 
>  # The name of the math extension changed on Sphinx 1.4
>  if (major == 1 and minor > 3) or (major > 1):
> diff --git a/Documentation/kernel-hacking/hacking.rst
> b/Documentation/kernel-hacking/hacking.rst index a3ddb213a5e1..d707a0a61cc9
> 100644
> --- a/Documentation/kernel-hacking/hacking.rst
> +++ b/Documentation/kernel-hacking/hacking.rst
> @@ -601,7 +601,7 @@ Defined in ``include/linux/export.h``
> 
>  This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol
>  namespace. Symbol Namespaces are documented in
> -``Documentation/kbuild/namespaces.rst``.
> +:ref:`Documentation/core-api/symbol-namespaces.rst <Symbol Namespaces>`
> 
>  :c:func:`EXPORT_SYMBOL_NS_GPL()`
> 
>  --------------------------------
> @@ -610,7 +610,7 @@ Defined in ``include/linux/export.h``
> 
>  This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a
> symbol namespace. Symbol Namespaces are documented in
> -``Documentation/kbuild/namespaces.rst``.
> +:ref:`Documentation/core-api/symbol-namespaces.rst <Symbol Namespaces>`
> 
>  Routines and Conventions
>  ========================

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

[Mauro Carvalho Chehab]

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

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

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index fa2bfcd6df1d..f193bae85a36 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -40,6 +40,10 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel' ]
 
+# Ensure that autosectionlabel will produce unique names
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 1
+
 # 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")
-- 
2.24.1

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

[Federico Vaga]

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.

Fine with me

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

[Mauro Carvalho Chehab]

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

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

[Mauro Carvalho Chehab]

Em Fri, 20 Mar 2020 12:59:18 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> 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.

Hmm... actually no. maxdepth = 1 will only get the title of each
document.

It should be at least maxdepth = 2, but this is producing some warnings
here (part on some new patches I wrote, that aren't upstream yet).

I'll run some tests and send a new version of this patch.


> 
> 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



Thanks,
Mauro