docs: vm/page_owner: Use literal blocks for param description
PATCH 1/1 docs: vm/page_owner: Use literal blocks for param description
Subject: [PATCH] docs: vm/page_owner: Use literal blocks for param description
Sphinx generates hard-to-read lists of parameters at the bottom of the page. Fix them by putting literal-block markers of "::" in front of them.
---
Hello Andrew,
This is the first time I send a patch in your way. So I'm not sure this works as I intend.
If anything goes wrong, please let me know.
This issue is in discussion in a linux-doc thread triggered by a post from Haowen Bai [1]. (Warning: The thread looks confused due to Haowen's unnecessary uses of In-Reply-To: headers.) Jon suggested the route via your tree, but he keeps posting to linux-doc.
[1]: https://lore.kernel.org/all/[email protected]/
Haowen's patch uses tables to improve the look of param lists. I suggested him using literal blocks instead, but I failed to hear any response. So I'm sending my version of the fix in your way.
I believe this fix is worth for 5.18-rcX.
Side note 1: I see another patch queued for -next around here, which has broken indents by white spaces. You might want to fix or drop it.
Side note 2: page_owner.rst is not covered in MAINTAINERS. You might want to add an entry, maybe, under "PAGE TABLE CHECK".
Again, if there is anything I can do better, please let me know.
Best,
Akira
--
Documentation/vm/page_owner.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/vm/page_owner.rst +3 -2
@@ -110,7 +110,7 @@ Usage If you want to sort by the page nums of buf, use the ``-m`` parameter. The detailed parameters are: - fundamental function: + fundamental function:: Sort: -a Sort by memory allocation time.
@@ -122,7 +122,7 @@ Usage -s Sort by stack trace. -t Sort by times (default). - additional function: + additional function:: Cull: --cull <rules>
@@ -153,6 +153,7 @@ Usage STANDARD FORMAT SPECIFIERS ========================== +:: KEY LONG DESCRIPTION p pid process ID
base-commit: af2d861d4cd2a4da5137f795ee3509e6f944a25b
Signature · 1 line
2.25.1
Quoted 26 lines · Akira Yokosawa
Subject: [PATCH] docs: vm/page_owner: Use literal blocks for param description
Sphinx generates hard-to-read lists of parameters at the bottom of the page. Fix them by putting literal-block markers of "::" in front of them.
Signed-off-by Akira Yokosawa <[email protected]>Fixes 57f2b54a9379 ("Documentation/vm/page_owner.rst: update the documentation")Cc Shenghong Han <[email protected]>Cc Andrew Morton <[email protected]>Cc Haowen Bai <[email protected]>Cc Jonathan Corbet <[email protected]>Cc Alex Shi <[email protected]>---
Hello Andrew,This is the first time I send a patch in your way. So I'm not sure this works as I intend.
If anything goes wrong, please let me know.This issue is in discussion in a linux-doc thread triggered by a post from Haowen Bai [1]. (Warning: The thread looks confused due to Haowen's unnecessary uses of In-Reply-To: headers.) Jon suggested the route via your tree, but he keeps posting to linux-doc.
Quoted 6 lines
[1]: https://lore.kernel.org/all/[email protected]/
Haowen's patch uses tables to improve the look of param lists. I suggested him using literal blocks instead, but I failed to hear any response. So I'm sending my version of the fix in your way.
Dear Akira Yokosawa
Sorry for missing reply your mail, since I am out of work at that time. BTW, I'll try to work base on the newest Doc later.
Thank you for your suggestion and apply the typical format for parameter description.
Quoted 49 lines
I believe this fix is worth for 5.18-rcX.
Side note 1: I see another patch queued for -next around here, which has broken indents by white spaces. You might want to fix or drop it.
Side note 2:
page_owner.rstis not covered inMAINTAINERS. You might want to add an entry, maybe, under "PAGE TABLE CHECK".Again, if there is anything I can do better, please let me know.
Best,
Akira
--Documentation/vm/page_owner.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)Documentation/vm/page_owner.rst +3
-2@@ -110,7 +110,7 @@ Usage If you want to sort by the page nums of buf, use the ``-m`` parameter. The detailed parameters are: - fundamental function: + fundamental function:: Sort: -a Sort by memory allocation time.@@ -122,7 +122,7 @@ Usage -s Sort by stack trace. -t Sort by times (default). - additional function: + additional function:: Cull: --cull <rules>@@ -153,6 +153,7 @@ Usage STANDARD FORMAT SPECIFIERS ========================== +:: KEY LONG DESCRIPTION p pid process IDbase-commit:
af2d861d4cd2a4da5137f795ee3509e6f944a25b
Signature · 1 line
Haowen Bai
Quoted 7 lines · Akira Yokosawa
Subject: [PATCH] docs: vm/page_owner: Use literal blocks for param description
Sphinx generates hard-to-read lists of parameters at the bottom of the page. Fix them by putting literal-block markers of "::" in front of them.
Signed-off-by Akira Yokosawa <[email protected]>
LFTM
Quoted 75 lines
Fixes 57f2b54a9379 ("Documentation/vm/page_owner.rst: update the documentation")Cc Shenghong Han <[email protected]>Cc Andrew Morton <[email protected]>Cc Haowen Bai <[email protected]>Cc Jonathan Corbet <[email protected]>Cc Alex Shi <[email protected]>---
Hello Andrew,This is the first time I send a patch in your way. So I'm not sure this works as I intend.
If anything goes wrong, please let me know.This issue is in discussion in a linux-doc thread triggered by a post from Haowen Bai [1]. (Warning: The thread looks confused due to Haowen's unnecessary uses of In-Reply-To: headers.) Jon suggested the route via your tree, but he keeps posting to linux-doc.
[1]: https://lore.kernel.org/all/[email protected]/
Haowen's patch uses tables to improve the look of param lists. I suggested him using literal blocks instead, but I failed to hear any response. So I'm sending my version of the fix in your way.
I believe this fix is worth for 5.18-rcX.
Side note 1: I see another patch queued for -next around here, which has broken indents by white spaces. You might want to fix or drop it.
Side note 2:
page_owner.rstis not covered inMAINTAINERS. You might want to add an entry, maybe, under "PAGE TABLE CHECK".Again, if there is anything I can do better, please let me know.
Best,
Akira
--Documentation/vm/page_owner.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)Documentation/vm/page_owner.rst +3
-2@@ -110,7 +110,7 @@ Usage If you want to sort by the page nums of buf, use the ``-m`` parameter. The detailed parameters are: - fundamental function: + fundamental function:: Sort: -a Sort by memory allocation time.@@ -122,7 +122,7 @@ Usage -s Sort by stack trace. -t Sort by times (default). - additional function: + additional function:: Cull: --cull <rules>@@ -153,6 +153,7 @@ Usage STANDARD FORMAT SPECIFIERS ========================== +:: KEY LONG DESCRIPTION p pid process IDbase-commit:
af2d861d4cd2a4da5137f795ee3509e6f944a25b