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 <[email protected]>
---
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
On Fri, 22 Nov 2019 12:53:37 +0100
Federico Vaga <[email protected]> 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 <[email protected]>
> ---
> 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 <[email protected]>
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 <[email protected]>
Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
Signed-off-by: Jonathan Corbet <[email protected]>
---
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
On Friday, November 22, 2019 6:34:37 PM CET Jonathan Corbet wrote:
> On Fri, 22 Nov 2019 12:53:37 +0100
>
> Federico Vaga <[email protected]> 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 <[email protected]>
> > ---
> >
> > 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 <[email protected]>
> 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 <[email protected]>
> Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> 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
> ========================
Em Sun, 24 Nov 2019 18:02:02 +0100
Federico Vaga <[email protected]> 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
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 <[email protected]>
---
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
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
Em Fri, 20 Mar 2020 12:24:45 +0100
Federico Vaga <[email protected]> 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
Em Fri, 20 Mar 2020 12:59:18 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:
> Em Fri, 20 Mar 2020 12:24:45 +0100
> Federico Vaga <[email protected]> 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