[PATCH 0/3] docs: vm: Fix typo and build warnings

[PATCH 0/3] docs: vm: Fix typo and build warnings

[Tobin C. Harding]

From: "Tobin C. Harding" <tobin@kernel.org>

Hi Jon,

This patchset started as a spelling typo fix to the SLUB docs, while
doing this I noticed a few build warnings for vm/ so build warning fixes
make up the rest of the set.

Patch 3 uses an underscore instead of a hyphen in the label name.  This
clears the warning but I am not 100% sure this is the correct fix.

thanks,
Tobin.


Tobin C. Harding (3):
  docs: Fix SLUB docs typo
  docs: Add missing colon
  docs: Use underscore not hyphen in label

 Documentation/core-api/memory-allocation.rst | 2 +-
 Documentation/vm/index.rst                   | 2 +-
 Documentation/vm/slub.rst                    | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

-- 
2.20.1

[PATCH 1/3] docs: Fix SLUB docs typo

[Tobin C. Harding]

From: "Tobin C. Harding" <tobin@kernel.org>

There is a minor typo in SLUB documentation.

Fix typo.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 Documentation/vm/slub.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst
index 195928808..0871c5849 100644
--- a/Documentation/vm/slub.rst
+++ b/Documentation/vm/slub.rst
@@ -141,7 +141,7 @@ can be influenced by kernel parameters:
 	(list_lock) where contention may occur.
 
 ``slub_min_order``
-	specifies a minim order of slabs. A similar effect like
+	specifies a minimum order of slabs. A similar effect like
 	``slub_min_objects``.
 
 ``slub_max_order``
-- 
2.20.1

[PATCH 2/3] docs: Add missing colon

[Tobin C. Harding]

From: "Tobin C. Harding" <tobin@kernel.org>

sphinx emits warning

       WARNING: Inline emphasis start-string without end-string.

This is caused by a missing colon.

Add missing colon, clearing shpinx build warning.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 Documentation/vm/slub.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst
index 0871c5849..933ada436 100644
--- a/Documentation/vm/slub.rst
+++ b/Documentation/vm/slub.rst
@@ -66,7 +66,7 @@ Trying to find an issue in the dentry cache? Try::
 to only enable debugging on the dentry cache.  You may use an asterisk at the
 end of the slab name, in order to cover all slabs with the same prefix.  For
 example, here's how you can poison the dentry cache as well as all kmalloc
-slabs:
+slabs::
 
 	slub_debug=P,kmalloc-*,dentry
 
-- 
2.20.1

[PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

From: "Tobin C. Harding" <tobin@kernel.org>

sphinx emits warning

       WARNING: undefined label: memory-allocation ...

This seems to be caused by the use of a hyphen in the label name instead
of an underscore.  Using an underscore for the label name and the
reference clears the warning.

Use underscore not hyphen in label and reference.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---

Not 100% sure this is the correct fix, please review.

thanks

 Documentation/core-api/memory-allocation.rst | 2 +-
 Documentation/vm/index.rst                   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
index 8954a88ff..39f35ebdc 100644
--- a/Documentation/core-api/memory-allocation.rst
+++ b/Documentation/core-api/memory-allocation.rst
@@ -1,4 +1,4 @@
-.. _memory-allocation:
+.. _memory_allocation:
 
 =======================
 Memory Allocation Guide
diff --git a/Documentation/vm/index.rst b/Documentation/vm/index.rst
index 2b3ab3a1c..b58cc3bfe 100644
--- a/Documentation/vm/index.rst
+++ b/Documentation/vm/index.rst
@@ -4,7 +4,7 @@ Linux Memory Management Documentation
 
 This is a collection of documents about the Linux memory management (mm)
 subsystem.  If you are looking for advice on simply allocating memory,
-see the :ref:`memory-allocation`.
+see the :ref:`memory_allocation`.
 
 User guides for MM features
 ===========================
-- 
2.20.1

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Mike Rapoport]

On Thu, Jan 31, 2019 at 03:06:23PM +1100, Tobin C. Harding wrote:
> From: "Tobin C. Harding" <tobin@kernel.org>
> 
> sphinx emits warning
> 
>        WARNING: undefined label: memory-allocation ...

Weird, for me it works fine. The generated html at kernel.org [1] also
seems to be Ok...

What version of sphinx do you use?

[1] https://www.kernel.org/doc/html/latest/vm/index.html
> 
> This seems to be caused by the use of a hyphen in the label name instead
> of an underscore.  Using an underscore for the label name and the
> reference clears the warning.
> 
> Use underscore not hyphen in label and reference.
> 
> Signed-off-by: Tobin C. Harding <tobin@kernel.org>
> ---
> 
> Not 100% sure this is the correct fix, please review.
> 
> thanks
> 
>  Documentation/core-api/memory-allocation.rst | 2 +-
>  Documentation/vm/index.rst                   | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
> index 8954a88ff..39f35ebdc 100644
> --- a/Documentation/core-api/memory-allocation.rst
> +++ b/Documentation/core-api/memory-allocation.rst
> @@ -1,4 +1,4 @@
> -.. _memory-allocation:
> +.. _memory_allocation:
> 
>  =======================
>  Memory Allocation Guide
> diff --git a/Documentation/vm/index.rst b/Documentation/vm/index.rst
> index 2b3ab3a1c..b58cc3bfe 100644
> --- a/Documentation/vm/index.rst
> +++ b/Documentation/vm/index.rst
> @@ -4,7 +4,7 @@ Linux Memory Management Documentation
> 
>  This is a collection of documents about the Linux memory management (mm)
>  subsystem.  If you are looking for advice on simply allocating memory,
> -see the :ref:`memory-allocation`.
> +see the :ref:`memory_allocation`.
> 
>  User guides for MM features
>  ===========================
> -- 
> 2.20.1
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH 2/3] docs: Add missing colon

[Mike Rapoport]

On Thu, Jan 31, 2019 at 03:06:22PM +1100, Tobin C. Harding wrote:
> From: "Tobin C. Harding" <tobin@kernel.org>
> 
> sphinx emits warning
> 
>        WARNING: Inline emphasis start-string without end-string.
> 
> This is caused by a missing colon.
> 
> Add missing colon, clearing shpinx build warning.
> 
> Signed-off-by: Tobin C. Harding <tobin@kernel.org>

Acked-by: Mike Rapoport <rppt@linux.ibm.com>

> ---
>  Documentation/vm/slub.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst
> index 0871c5849..933ada436 100644
> --- a/Documentation/vm/slub.rst
> +++ b/Documentation/vm/slub.rst
> @@ -66,7 +66,7 @@ Trying to find an issue in the dentry cache? Try::
>  to only enable debugging on the dentry cache.  You may use an asterisk at the
>  end of the slab name, in order to cover all slabs with the same prefix.  For
>  example, here's how you can poison the dentry cache as well as all kmalloc
> -slabs:
> +slabs::
> 
>  	slub_debug=P,kmalloc-*,dentry
> 
> -- 
> 2.20.1
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH 1/3] docs: Fix SLUB docs typo

[Mike Rapoport]

On Thu, Jan 31, 2019 at 03:06:21PM +1100, Tobin C. Harding wrote:
> From: "Tobin C. Harding" <tobin@kernel.org>
> 
> There is a minor typo in SLUB documentation.
> 
> Fix typo.
> 
> Signed-off-by: Tobin C. Harding <tobin@kernel.org>

Acked-by: Mike Rapoport <rppt@linux.ibm.com>

> ---
>  Documentation/vm/slub.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst
> index 195928808..0871c5849 100644
> --- a/Documentation/vm/slub.rst
> +++ b/Documentation/vm/slub.rst
> @@ -141,7 +141,7 @@ can be influenced by kernel parameters:
>  	(list_lock) where contention may occur.
> 
>  ``slub_min_order``
> -	specifies a minim order of slabs. A similar effect like
> +	specifies a minimum order of slabs. A similar effect like
>  	``slub_min_objects``.
> 
>  ``slub_max_order``
> -- 
> 2.20.1
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

On Thu, Jan 31, 2019 at 11:27:57AM +0200, Mike Rapoport wrote:
> On Thu, Jan 31, 2019 at 03:06:23PM +1100, Tobin C. Harding wrote:
> > From: "Tobin C. Harding" <tobin@kernel.org>
> > 
> > sphinx emits warning
> > 
> >        WARNING: undefined label: memory-allocation ...
> 
> Weird, for me it works fine. The generated html at kernel.org [1] also
> seems to be Ok...
> 
> What version of sphinx do you use?

Thanks for looking at this Mike.  I was running 1.4, I see there is a v2
out so I'll upgrade but if the warning doesn't show for you then I'd say
we just drop this patch.

Jon,

Is it within your usual workflow to take just the first two patches from
this series or would you like me to spin another version without the
final patch in it?


thanks,
Tobin.

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Jonathan Corbet]

On Fri, 1 Feb 2019 07:56:08 +1100
"Tobin C. Harding" <me@tobin.cc> wrote:

> > > From: "Tobin C. Harding" <tobin@kernel.org>
> > > 
> > > sphinx emits warning
> > > 
> > >        WARNING: undefined label: memory-allocation ...  
> > 
> > Weird, for me it works fine. The generated html at kernel.org [1] also
> > seems to be Ok...
> > 
> > What version of sphinx do you use?  
> 
> Thanks for looking at this Mike.  I was running 1.4, I see there is a v2
> out so I'll upgrade but if the warning doesn't show for you then I'd say
> we just drop this patch.
> 
> Jon,
> 
> Is it within your usual workflow to take just the first two patches from
> this series or would you like me to spin another version without the
> final patch in it?

We currently document that 1.4 is supposed to work, so we should stick to
that; I think I'll go ahead and apply all three patches.

We should maybe consider dragging our minimum version forward a bit, or
else we might want to document this particular gotcha.

Thanks,

jon

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Mike Rapoport]

On Fri, Feb 01, 2019 at 04:03:10PM -0700, Jonathan Corbet wrote:
> On Fri, 1 Feb 2019 07:56:08 +1100
> "Tobin C. Harding" <me@tobin.cc> wrote:
> 
> > > > From: "Tobin C. Harding" <tobin@kernel.org>
> > > > 
> > > > sphinx emits warning
> > > > 
> > > >        WARNING: undefined label: memory-allocation ...  
> > > 
> > > Weird, for me it works fine. The generated html at kernel.org [1] also
> > > seems to be Ok...
> > > 
> > > What version of sphinx do you use?  
> > 
> > Thanks for looking at this Mike.  I was running 1.4, I see there is a v2
> > out so I'll upgrade but if the warning doesn't show for you then I'd say
> > we just drop this patch.
> > 
> > Jon,
> > 
> > Is it within your usual workflow to take just the first two patches from
> > this series or would you like me to spin another version without the
> > final patch in it?
> 
> We currently document that 1.4 is supposed to work, so we should stick to
> that; I think I'll go ahead and apply all three patches.
>
> We should maybe consider dragging our minimum version forward a bit, or
> else we might want to document this particular gotcha.

I have 1.4.6 (the one listed in sphinx.rst) and everything worked just
fine...
 
> Thanks,
> 
> jon
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

On Sat, Feb 02, 2019 at 04:32:10PM +0200, Mike Rapoport wrote:
> On Fri, Feb 01, 2019 at 04:03:10PM -0700, Jonathan Corbet wrote:
> > On Fri, 1 Feb 2019 07:56:08 +1100
> > "Tobin C. Harding" <me@tobin.cc> wrote:
> > 
> > > > > From: "Tobin C. Harding" <tobin@kernel.org>
> > > > > 
> > > > > sphinx emits warning
> > > > > 
> > > > >        WARNING: undefined label: memory-allocation ...  
> > > > 
> > > > Weird, for me it works fine. The generated html at kernel.org [1] also
> > > > seems to be Ok...
> > > > 
> > > > What version of sphinx do you use?  
> > > 
> > > Thanks for looking at this Mike.  I was running 1.4, I see there is a v2
> > > out so I'll upgrade but if the warning doesn't show for you then I'd say
> > > we just drop this patch.
> > > 
> > > Jon,
> > > 
> > > Is it within your usual workflow to take just the first two patches from
> > > this series or would you like me to spin another version without the
> > > final patch in it?
> > 
> > We currently document that 1.4 is supposed to work, so we should stick to
> > that; I think I'll go ahead and apply all three patches.
> >
> > We should maybe consider dragging our minimum version forward a bit, or
> > else we might want to document this particular gotcha.
> 
> I have 1.4.6 (the one listed in sphinx.rst) and everything worked just
> fine...

FWIW I'm running 1.4.9


thanks,
Tobin.

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Mike Rapoport]

On Mon, Feb 04, 2019 at 10:20:35AM +1100, Tobin C. Harding wrote:
> On Sat, Feb 02, 2019 at 04:32:10PM +0200, Mike Rapoport wrote:
> > On Fri, Feb 01, 2019 at 04:03:10PM -0700, Jonathan Corbet wrote:
> > > On Fri, 1 Feb 2019 07:56:08 +1100
> > > "Tobin C. Harding" <me@tobin.cc> wrote:
> > > 
> > > > > > From: "Tobin C. Harding" <tobin@kernel.org>
> > > > > > 
> > > > > > sphinx emits warning
> > > > > > 
> > > > > >        WARNING: undefined label: memory-allocation ...  
> > > > > 
> > > > > Weird, for me it works fine. The generated html at kernel.org [1] also
> > > > > seems to be Ok...
> > > > > 
> > > > > What version of sphinx do you use?  
> > > > 
> > > > Thanks for looking at this Mike.  I was running 1.4, I see there is a v2
> > > > out so I'll upgrade but if the warning doesn't show for you then I'd say
> > > > we just drop this patch.
> > > > 
> > > > Jon,
> > > > 
> > > > Is it within your usual workflow to take just the first two patches from
> > > > this series or would you like me to spin another version without the
> > > > final patch in it?
> > > 
> > > We currently document that 1.4 is supposed to work, so we should stick to
> > > that; I think I'll go ahead and apply all three patches.
> > >
> > > We should maybe consider dragging our minimum version forward a bit, or
> > > else we might want to document this particular gotcha.
> > 
> > I have 1.4.6 (the one listed in sphinx.rst) and everything worked just
> > fine...
> 
> FWIW I'm running 1.4.9

I've tried with 1.4.9 and I haven't seen this warning.

Tobin, does this warning appear only for memory-allocation or for other
docs as well?
 
 
> thanks,
> Tobin.
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

On Sat, Feb 02, 2019 at 04:32:10PM +0200, Mike Rapoport wrote:
> On Fri, Feb 01, 2019 at 04:03:10PM -0700, Jonathan Corbet wrote:
> > On Fri, 1 Feb 2019 07:56:08 +1100
> > "Tobin C. Harding" <me@tobin.cc> wrote:
> > 
> > > > > From: "Tobin C. Harding" <tobin@kernel.org>
> > > > > 
> > > > > sphinx emits warning
> > > > > 
> > > > >        WARNING: undefined label: memory-allocation ...  
> > > > 
> > > > Weird, for me it works fine. The generated html at kernel.org [1] also
> > > > seems to be Ok...
> > > > 
> > > > What version of sphinx do you use?  
> > > 
> > > Thanks for looking at this Mike.  I was running 1.4, I see there is a v2
> > > out so I'll upgrade but if the warning doesn't show for you then I'd say
> > > we just drop this patch.
> > > 
> > > Jon,
> > > 
> > > Is it within your usual workflow to take just the first two patches from
> > > this series or would you like me to spin another version without the
> > > final patch in it?
> > 
> > We currently document that 1.4 is supposed to work, so we should stick to
> > that; I think I'll go ahead and apply all three patches.
> >
> > We should maybe consider dragging our minimum version forward a bit, or
> > else we might want to document this particular gotcha.
> 
> I have 1.4.6 (the one listed in sphinx.rst) and everything worked just
> fine...

I tried to investigate this further and I am unable to reproduce the
original warning.  I'm using python virtual environment as directed by
the output of `make htmldocs` so the environment should not have
changed.  The only other plausible explanation seems to be that I've
gone mad and can't remember what I was doing three days ago.

Thanks for your patience.


	Tobin.

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Jonathan Corbet]

On Tue, 5 Feb 2019 08:12:20 +1100
"Tobin C. Harding" <me@tobin.cc> wrote:

> I tried to investigate this further and I am unable to reproduce the
> original warning.  I'm using python virtual environment as directed by
> the output of `make htmldocs` so the environment should not have
> changed.  The only other plausible explanation seems to be that I've
> gone mad and can't remember what I was doing three days ago.

You are not the first to have reported such issues, though; I've seen a
couple of things go by in the past.  Until we understand what is going on,
it's probably best to avoid hyphens in labels.

Thanks,

jon

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Markus Heiser]

Am 05.02.19 um 00:03 schrieb Jonathan Corbet:
> On Tue, 5 Feb 2019 08:12:20 +1100
> "Tobin C. Harding" <me@tobin.cc> wrote:
> 
>> I tried to investigate this further and I am unable to reproduce the
>> original warning.  I'm using python virtual environment as directed by
>> the output of `make htmldocs` so the environment should not have
>> changed.  The only other plausible explanation seems to be that I've
>> gone mad and can't remember what I was doing three days ago.
> 
> You are not the first to have reported such issues, though; I've seen a
> couple of things go by in the past.  Until we understand what is going on,
> it's probably best to avoid hyphens in labels.

Many errors are not reported again in rebuilds.

To reproduce this error run 'make cleandocs htmldocs' first.  Then you will see
this error message (I'am on current docs-next from Jon using Sphinx v1.8.3 ):

   Documentation/core-api/mm-api.rst:22: WARNING: undefined label: \
     memory-allocation (if the link has no caption ...)

In mm-api.rst you find this include:

.. kernel-doc:: include/linux/slab.h
    :internal:


And in slab.h you see a kmalloc DOC with a :ref:`..<memory-allocation>`


/**
  * kmalloc - allocate memory
  * @size: how many bytes of memory are required.
  * @flags: the type of memory to allocate.
  *
  * kmalloc is the normal method of allocating memory
  * for objects smaller than page size in the kernel.
  *
  * The @flags argument may be one of the GFP flags defined at
  * include/linux/gfp.h and described at
  * :ref:`Documentation/core-api/mm-api.rst <mm-api-gfp-flags>`
  *
  * The recommended usage of the @flags is described at
  * :ref:`Documentation/core-api/memory-allocation.rst <memory-allocation>`


With Tobin's patch applied to Jon's docs-next (cd7198fc959), this error comes up
the first time (for me).

   Can we please revert cd7198fc959 / Thanks

@Tobin can you pleases test to revert cd7198fc959 and make a full build with
'cleandocs' first .. may this error comes up again for you and we can
investigate any further .. if this depends to sphinx-Version or what ever.


-- Markus --

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

On Tue, Feb 05, 2019 at 09:30:46AM +0100, Markus Heiser wrote:
> Am 05.02.19 um 00:03 schrieb Jonathan Corbet:
> > On Tue, 5 Feb 2019 08:12:20 +1100
> > "Tobin C. Harding" <me@tobin.cc> wrote:
> > 
> > > I tried to investigate this further and I am unable to reproduce the
> > > original warning.  I'm using python virtual environment as directed by
> > > the output of `make htmldocs` so the environment should not have
> > > changed.  The only other plausible explanation seems to be that I've
> > > gone mad and can't remember what I was doing three days ago.
> > 
> > You are not the first to have reported such issues, though; I've seen a
> > couple of things go by in the past.  Until we understand what is going on,
> > it's probably best to avoid hyphens in labels.

This statement is not sitting well with me Jon, we are using hyphens in
labels all over the place with *almost* no issue.  Seems we either
change them all or none of them.  (FTR I think we should not change any
of them.)

> Many errors are not reported again in rebuilds.

It's more than that.  Seems that no .o files means dependencies are not
the same in docs directories to *usual* source code directories, as in
this example, a file with an outdated label was not rebuilt since it
wasn't touched.

Note to self, always do clean build for docs patches.  Thanks.

> To reproduce this error run 'make cleandocs htmldocs' first.  Then you will see
> this error message (I'am on current docs-next from Jon using Sphinx v1.8.3 ):
> 
>   Documentation/core-api/mm-api.rst:22: WARNING: undefined label: \
>     memory-allocation (if the link has no caption ...)

Can confirm I also get this warning, sloppy work by me I missed one
label.  Second note to self, grep the whole tree not just /Documentation

Thanks for reporting this.

> In mm-api.rst you find this include:
> 
> .. kernel-doc:: include/linux/slab.h
>    :internal:
> 
> 
> And in slab.h you see a kmalloc DOC with a :ref:`..<memory-allocation>`
> 
> 
> /**
>  * kmalloc - allocate memory
>  * @size: how many bytes of memory are required.
>  * @flags: the type of memory to allocate.
>  *
>  * kmalloc is the normal method of allocating memory
>  * for objects smaller than page size in the kernel.
>  *
>  * The @flags argument may be one of the GFP flags defined at
>  * include/linux/gfp.h and described at
>  * :ref:`Documentation/core-api/mm-api.rst <mm-api-gfp-flags>`
>  *
>  * The recommended usage of the @flags is described at
>  * :ref:`Documentation/core-api/memory-allocation.rst <memory-allocation>`
> 
> 
> With Tobin's patch applied to Jon's docs-next (cd7198fc959), this error comes up
> the first time (for me).
> 
>   Can we please revert cd7198fc959 / Thanks

I agree with you Markus, I'd like to see this reverted.  Jon, your the
boss, if you want this patch to stay I can send in a patch to fix the
undefined label that this patch misses.

> @Tobin can you pleases test to revert cd7198fc959 and make a full build with
> 'cleandocs' first .. may this error comes up again for you and we can
> investigate any further .. if this depends to sphinx-Version or what ever.

With patch reverted, on docs-next, I've got 0 'undefined labels'
warnings.

Hope this adds more help than confusion :)


	Tobin

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Markus Heiser]

Am 06.02.19 um 05:27 schrieb Tobin C. Harding:
 > Seems we either change them all or none of them.

Both are OK .. from the spec ...

"Simple reference names are single words consisting of alphanumerics plus
isolated (no two adjacent) internal hyphens, underscores, periods, colons
and plus signs; no whitespace or other characters are allowed." [1]


 >> Many errors are not reported again in rebuilds.
 >
 > It's more than that.  Seems that no .o files means dependencies are not
 > the same in docs directories to *usual* source code directories, as in
 > this example, a file with an outdated label was not rebuilt since it
 > wasn't touched.

Right, this is what they call the 'doctree' files (see [2] for build
phases), one for every source file.  ATM they are located in the hidden
folder 'output/.doctree'.  OT here, just to mentioning: this will result in
the folder being exported at the end, e.g. kernel.org:

   https://www.kernel.org/doc/html/latest/.doctrees/

 > Note to self, always do clean build for docs patches.  Thanks.
 >
 >> To reproduce this error run 'make cleandocs htmldocs' first.  Then you will see
 >> this error message (I'am on current docs-next from Jon using Sphinx v1.8.3 ):
 >>
 >>    Documentation/core-api/mm-api.rst:22: WARNING: undefined label: \
 >>      memory-allocation (if the link has no caption ...)
 >
 > Can confirm I also get this warning,
..
 > With patch reverted, on docs-next, I've got 0 'undefined labels'
 > warnings.

Thanks for verification.

[1] 
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#reference-names
[2] http://www.sphinx-doc.org/en/master/extdev/index.html#build-phases


  -- Markus --

Re: [PATCH 3/3] docs: Use underscore not hyphen in label

[Tobin C. Harding]

On Wed, Feb 06, 2019 at 08:49:38AM +0100, Markus Heiser wrote:
> Am 06.02.19 um 05:27 schrieb Tobin C. Harding:
> > Seems we either change them all or none of them.
> 
> Both are OK .. from the spec ...
> 
> "Simple reference names are single words consisting of alphanumerics plus
> isolated (no two adjacent) internal hyphens, underscores, periods, colons
> and plus signs; no whitespace or other characters are allowed." [1]
> 
> 
> >> Many errors are not reported again in rebuilds.
> >
> > It's more than that.  Seems that no .o files means dependencies are not
> > the same in docs directories to *usual* source code directories, as in
> > this example, a file with an outdated label was not rebuilt since it
> > wasn't touched.
> 
> Right, this is what they call the 'doctree' files (see [2] for build
> phases), one for every source file.  ATM they are located in the hidden
> folder 'output/.doctree'.  OT here, just to mentioning: this will result in
> the folder being exported at the end, e.g. kernel.org:
> 
>   https://www.kernel.org/doc/html/latest/.doctrees/
> 
> > Note to self, always do clean build for docs patches.  Thanks.
> >
> >> To reproduce this error run 'make cleandocs htmldocs' first.  Then you will see
> >> this error message (I'am on current docs-next from Jon using Sphinx v1.8.3 ):
> >>
> >>    Documentation/core-api/mm-api.rst:22: WARNING: undefined label: \
> >>      memory-allocation (if the link has no caption ...)
> >
> > Can confirm I also get this warning,
> ..
> > With patch reverted, on docs-next, I've got 0 'undefined labels'
> > warnings.
> 
> Thanks for verification.
> 
> [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#reference-names
> [2] http://www.sphinx-doc.org/en/master/extdev/index.html#build-phases
> 
> 
>  -- Markus --
> 

Thanks Markus, I appreciate the information.


	Tobin.