docs: vm: Fix typo and build warnings
Subsystems (2)
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
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
@@ -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
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.
Signed-off-by Tobin C. Harding <[email protected]>
Quoted 20 lines
--- Documentation/vm/slub.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/vm/slub.rst +1
-1@@ -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.
PATCH 2/3 docs: Add missing colon
In reply to Tobin C. HardingFrom: "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
@@ -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
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.
Signed-off-by Tobin C. Harding <[email protected]>
Quoted 20 lines
--- Documentation/vm/slub.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/vm/slub.rst +1
-1@@ -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-*,dentrySignature · 1 line
2.20.1
Signature · 2 lines
Sincerely yours, Mike.
PATCH 3/3 docs: Use underscore not hyphen in label
In reply to Tobin C. HardingFrom: "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
@@ -1,4 +1,4 @@ -.. _memory-allocation: +.. _memory_allocation: ======================= Memory Allocation Guide
Documentation/vm/index.rst +1 -1
@@ -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
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.
Signed-off-by Tobin C. Harding <[email protected]>---
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@@ -1,4 +1,4 @@ -.. _memory-allocation: +.. _memory_allocation: ======================= Memory Allocation GuideDocumentation/vm/index.rst +1
-1@@ -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.
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.
Jonathan Corbet
maintainerRe: [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
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.
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.
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.
Re: [PATCH 3/3] docs: Use underscore not hyphen in label
In reply to Mike RapoportQuoted 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.
Jonathan Corbet
maintainerRe: [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 htmldocsso 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
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 htmldocsso 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 --
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 htmldocsso 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.rstyou find this include:.. kernel-doc::
include/linux/slab.h
:internal:And in
slab.hyou 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.hand 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
cd7198fc959and 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
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 --
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.