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

[Federico Vaga <federico.vaga@vaga.pv.it>]

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