Skip to contentSkip to conversation

docs: vm: Fix typo and build warnings

PATCH In review Tobin C. Harding 4 participants 18 messages Jan 31, 2019 – Feb 6, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover docs: vm: Fix typo and build warnings

From: "Tobin C. Harding" <[email protected]>

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(-)
Signature · 1 line
2.20.1
#1 lore raw

PATCH 1/3 docs: Fix SLUB docs typo

From: "Tobin C. Harding" <[email protected]>

There is a minor typo in SLUB documentation.

Fix typo.

---
 Documentation/vm/slub.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/vm/slub.rst +1 -1
index 195928808..0871c5849 100644
@@ -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``
Signature · 1 line
2.20.1
Acked-by on v1 1/3
#2 lore raw

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

Quoted 7 lines · Tobin C. Harding

From: "Tobin C. Harding" <[email protected]>

There is a minor typo in SLUB documentation.

Fix typo.

Quoted 20 lines
---
 Documentation/vm/slub.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/vm/slub.rst +1 -1
index 195928808..0871c5849 100644
@@ -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``
Signature · 1 line
2.20.1
Signature · 2 lines
Sincerely yours,
Mike.
#3 lore raw

PATCH 2/3 docs: Add missing colon

In reply to Tobin C. Harding

From: "Tobin C. Harding" <[email protected]>

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.

---
 Documentation/vm/slub.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/vm/slub.rst +1 -1
index 0871c5849..933ada436 100644
@@ -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
 
Signature · 1 line
2.20.1
Acked-by on v1 2/3
#4 lore raw

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

Quoted 11 lines · Tobin C. Harding

From: "Tobin C. Harding" <[email protected]>

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.

Quoted 20 lines
---
 Documentation/vm/slub.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/vm/slub.rst +1 -1
index 0871c5849..933ada436 100644
@@ -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
 
Signature · 1 line
2.20.1
Signature · 2 lines
Sincerely yours,
Mike.
#5 lore raw

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

In reply to Tobin C. Harding

From: "Tobin C. Harding" <[email protected]>

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.

---

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(-)
Documentation/core-api/memory-allocation.rst +1 -1
index 8954a88ff..39f35ebdc 100644
@@ -1,4 +1,4 @@
-.. _memory-allocation:
+.. _memory_allocation:
 
 =======================
 Memory Allocation Guide
Documentation/vm/index.rst +1 -1
index 2b3ab3a1c..b58cc3bfe 100644
@@ -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
 ===========================
Signature · 1 line
2.20.1
#6 lore raw

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

Quoted 5 lines · Tobin C. Harding

From: "Tobin C. Harding" <[email protected]>

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

Quoted 44 lines

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.

---

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(-)
Documentation/core-api/memory-allocation.rst +1 -1
index 8954a88ff..39f35ebdc 100644
@@ -1,4 +1,4 @@
-.. _memory-allocation:
+.. _memory_allocation:
 
 =======================
 Memory Allocation Guide
Documentation/vm/index.rst +1 -1
index 2b3ab3a1c..b58cc3bfe 100644
@@ -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
 ===========================
Signature · 1 line
2.20.1
Signature · 2 lines
Sincerely yours,
Mike.
#7 lore raw

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

Quoted 11 lines · Mike Rapoport
Quoted 5 lines · Tobin C. Harding

From: "Tobin C. Harding" <[email protected]>

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.

maintainer
#8 lore raw

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

Quoted 15 lines · On Fri, 1 Feb 2019 07:56:08 +1100 "Tobin C. Harding" <[email protected]> wrote:
Quoted 10 lines
Quoted 5 lines

From: "Tobin C. Harding" <[email protected]>

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.

Quoted 5 lines

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

#9 lore raw

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

Quoted 24 lines · Jonathan Corbet
Quoted 15 lines · On Fri, 1 Feb 2019 07:56:08 +1100 "Tobin C. Harding" <[email protected]> wrote:
Quoted 10 lines
Quoted 5 lines

From: "Tobin C. Harding" <[email protected]>

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.

Quoted 5 lines

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?

Quoted 5 lines

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

Quoted 4 lines

Thanks,

jon

Signature · 2 lines
Sincerely yours,
Mike.
#10 lore raw

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

Quoted 25 lines · Mike Rapoport
Quoted 24 lines · Jonathan Corbet
Quoted 20 lines · On Fri, 1 Feb 2019 07:56:08 +1100 "Tobin C. Harding" <[email protected]> wrote:
Quoted 10 lines
Quoted 5 lines

From: "Tobin C. Harding" <[email protected]>

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?

Quoted 8 lines
Quoted 5 lines

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.

#11 lore raw

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

Quoted 29 lines · Tobin C. Harding
Quoted 28 lines · Mike Rapoport
Quoted 27 lines · Jonathan Corbet
Quoted 15 lines · On Fri, 1 Feb 2019 07:56:08 +1100 "Tobin C. Harding" <[email protected]> wrote:
Quoted 10 lines
Quoted 5 lines

From: "Tobin C. Harding" <[email protected]>

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.

Quoted 5 lines

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.

Quoted 7 lines
Quoted 5 lines
Quoted 2 lines

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?

Quoted 3 lines

thanks,
Tobin.

Signature · 2 lines
Sincerely yours,
Mike.
#12 lore raw

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

In reply to Mike Rapoport
Quoted 25 lines · Mike Rapoport
Quoted 24 lines · Jonathan Corbet
Quoted 20 lines · On Fri, 1 Feb 2019 07:56:08 +1100 "Tobin C. Harding" <[email protected]> wrote:
Quoted 10 lines
Quoted 5 lines

From: "Tobin C. Harding" <[email protected]>

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?

Quoted 8 lines
Quoted 5 lines

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.

maintainer
#13 lore raw

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

Quoted 5 lines · On Tue, 5 Feb 2019 08:12:20 +1100 "Tobin C. Harding" <[email protected]> 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

#14 lore raw

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

Am 05.02.19 um 00:03 schrieb Jonathan Corbet:

Quoted 9 lines
Quoted 5 lines · On Tue, 5 Feb 2019 08:12:20 +1100 "Tobin C. Harding" <[email protected]> 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.

Quoted 3 lines

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

#15 lore raw

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

Quoted 13 lines · Markus Heiser

Am 05.02.19 um 00:03 schrieb Jonathan Corbet:

Quoted 12 lines
Quoted 5 lines · On Tue, 5 Feb 2019 08:12:20 +1100 "Tobin C. Harding" <[email protected]> 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.)

Quoted 1 line

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.

Quoted 5 lines

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.

Quoted 25 lines

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>

Quoted 4 lines

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.

Quoted 3 lines

@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

#16 lore raw

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

Am 06.02.19 um 05:27 schrieb Tobin C. Harding:

Quoted 1 line

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]

Quoted 6 lines
Quoted 1 line

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/

Quoted 9 lines

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

Quoted 5 lines

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,

..

Quoted 2 lines

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

#17 lore raw

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

Quoted 37 lines · Markus Heiser

Am 06.02.19 um 05:27 schrieb Tobin C. Harding:

Quoted 1 line

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]

Quoted 6 lines
Quoted 1 line

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/

Quoted 9 lines

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

Quoted 5 lines

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,

..

Quoted 2 lines

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

Quoted 8 lines

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.