Documentation: doc-guide: Add missing page titles
v3 cover Documentation: doc-guide: Add missing page titles
Documentation/doc-guide/{kernel-doc,sphinx}.rst are lacking page titles, thus top-level table of contents for doc-guide directly shows chapter headings instead.
Add them.
Changes since v2 [1]:
- Promote only two chapter headings in kernel-doc.rst (suggested by Akira Yokosawa)
- Add Reviewed-by from Mauro Carvalho Chehab for 2/2
[1]: https://lore.kernel.org/linux-doc/[email protected]/
Bagas Sanjaya (2):
Documentation: kernel-doc: Promote two chapter headings to page title
Documentation: sphinx: replace "Introduction" chapter heading with
page title
Documentation/doc-guide/kernel-doc.rst | 2 ++ Documentation/doc-guide/sphinx.rst | 5 +++-- 2 files changed, 5 insertions(+), 2 deletions(-)
base-commit: f443e374ae131c168a065ea1748feac6b2e76613
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH v3 1/2 Documentation: kernel-doc: Promote two chapter headings to page title
Promote two chapter headings, named "Writing kernel-doc comments" and "Including kernel-doc comments" to page title. These titles deserve their own chapters in PDF output, although these will also appear as two separate titles in table of contents in HTML output.
--- Documentation/doc-guide/kernel-doc.rst | 2 ++ 1 file changed, 2 insertions(+)
Documentation/doc-guide/kernel-doc.rst +2 -0
@@ -1,3 +1,4 @@ +=========================== Writing kernel-doc comments ===========================
@@ -436,6 +437,7 @@ The title following ``DOC:`` acts as a heading within the source file, but also as an identifier for extracting the documentation comment. Thus, the title must be unique within the file. +============================= Including kernel-doc comments =============================
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH v3 2/2 Documentation: sphinx: replace "Introduction" chapter heading with page title
In reply to Bagas SanjayaReplace first chapter heading ("Introduction") with page title named "Using Sphinx for kernel documentation". This way, the first-level TOC for doc-guide contains title instead of chapter headings for this page.
--- Documentation/doc-guide/sphinx.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/doc-guide/sphinx.rst +3 -2
@@ -1,7 +1,8 @@ .. _sphinxdoc: -Introduction -============ +===================================== +Using Sphinx for kernel documentation +===================================== The Linux kernel uses `Sphinx`_ to generate pretty documentation from `reStructuredText`_ files under ``Documentation``. To build the documentation in
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Re: [PATCH v3 1/2] Documentation: kernel-doc: Promote two chapter headings to page title
In reply to Bagas SanjayaQuoted 4 lines · Bagas Sanjaya
Promote two chapter headings, named "Writing kernel-doc comments" and "Including kernel-doc comments" to page title. These titles deserve their own chapters in PDF output, although these will also appear as two separate titles in table of contents in HTML output.
As Mauro and I have pointed out, this change won't have any effect in the resulting HTML and PDF docs. No difference *at all*.
Why do you think this change is worthwhile.
Please convince us!
Quoted 13 lines
Cc Jonathan Corbet <[email protected]>Cc "David S. Miller" <[email protected]>Cc Greg Kroah-Hartman <[email protected]>Cc Tony Nguyen <[email protected]>Cc Vinod Koul <[email protected]>Cc Daniel Borkmann <[email protected]>Cc Mauro Carvalho Chehab <[email protected]>Cc Akira Yokosawa <[email protected]>Cc "Rafael J. Wysocki" <[email protected]>Cc Jens Axboe <[email protected]>Suggested-by Akira Yokosawa <[email protected]>
Please don't put this Suggested-by: at the moment.
Thanks, Akira
Quoted 22 lines
Signed-off-by Bagas Sanjaya <[email protected]>--- Documentation/doc-guide/kernel-doc.rst | 2 ++ 1 file changed, 2 insertions(+)Documentation/doc-guide/kernel-doc.rst +2
-0@@ -1,3 +1,4 @@ +=========================== Writing kernel-doc comments ===========================@@ -436,6 +437,7 @@ The title following ``DOC:`` acts as a heading within the source file, but also as an identifier for extracting the documentation comment. Thus, the title must be unique within the file. +============================= Including kernel-doc comments =============================
Re: [PATCH v3 1/2] Documentation: kernel-doc: Promote two chapter headings to page title
Quoted 7 lines · Akira Yokosawa
Quoted 4 lines · Bagas Sanjaya
Promote two chapter headings, named "Writing kernel-doc comments" and "Including kernel-doc comments" to page title. These titles deserve their own chapters in PDF output, although these will also appear as two separate titles in table of contents in HTML output.
Quoted 7 lines
As Mauro and I have pointed out, this change won't have any effect in the resulting HTML and PDF docs. No difference *at all*.
Why do you think this change is worthwhile.
Please convince us!
My intention is to give page title for kernel-doc.rst, according to documentation guideline at [1].
Quoted 14 lines
Quoted 13 lines
Cc Jonathan Corbet <[email protected]>Cc "David S. Miller" <[email protected]>Cc Greg Kroah-Hartman <[email protected]>Cc Tony Nguyen <[email protected]>Cc Vinod Koul <[email protected]>Cc Daniel Borkmann <[email protected]>Cc Mauro Carvalho Chehab <[email protected]>Cc Akira Yokosawa <[email protected]>Cc "Rafael J. Wysocki" <[email protected]>Cc Jens Axboe <[email protected]>Suggested-by Akira Yokosawa <[email protected]>
Quoted 4 lines
Please don't put this Suggested-by: at the moment.
Thanks, Akira
OK, will drop the trailer.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Re: [PATCH v3 1/2] Documentation: kernel-doc: Promote two chapter headings to page title
[Dropped irrelevant CCs]
Hi Bagas,
First of all, can I ask you to refrain from submitting new versions everyday? It is one of the most frowned-upon behavior in the kernel community.
I'm intentionally ignoring v4.
Quoted 11 lines · Bagas Sanjaya
Quoted 10 lines · Akira Yokosawa
Quoted 4 lines · Bagas Sanjaya
Promote two chapter headings, named "Writing kernel-doc comments" and "Including kernel-doc comments" to page title. These titles deserve their own chapters in PDF output, although these will also appear as two separate titles in table of contents in HTML output.
As Mauro and I have pointed out, this change won't have any effect in the resulting HTML and PDF docs. No difference *at all*.
Quoted 7 lines
Quoted 4 lines
Why do you think this change is worthwhile.
Please convince us!
My intention is to give page title for
kernel-doc.rst, according to documentation guideline at [1].
I'm afraid I'm not convinced.
Let's see the history of this document.
It first appeared in commit 17defc282fe6 ("Documentation: add meta-documentation for Sphinx and kernel-doc") as a chapter among other topics which evolved into current Documentation/doc-guide/. Back then there was a proper document title of "Linux Kernel Documentation".
It was renamed "How to write kernel documentation" in commit 555af62431e6 ("docs: retitle the kernel-documentation.rst"), which you still find in Documentation/doc-guide/index.rst.
It got split by commit 1dc4bbf0b268 ("docs-rst: doc-guide:
split the kernel-documentation.rst contents") in 2016. The title markers have not been touched ever since.
This is why you find those markers one level below the ones suggested in the guideline.
I think the guideline predates the reorganization of Documentations/ into document-wise subdirectories. It needs some expansion regarding .rst docs included from index.rst files under subdirectories.
What does "document title" mean? The one in index.rst?
What happens when a .rst file has a "document title"-level title at the beginning? Would it be treated as a "chapter" level title?
What happens when an index.rst file is included from another index.rst file?
Which title is used as a "page title" in the HTML docs?
... and so on.
I'd like to suggest you do the expansion of the guideline itself, which will be much appreciated.
Thanks, Akira
Quoted 1 line
[...]
Re: [PATCH v3 1/2] Documentation: kernel-doc: Promote two chapter headings to page title
Quoted 4 lines · Akira Yokosawa
[Dropped irrelevant CCs]
Hi Bagas,
Quoted 8 lines
First of all, can I ask you to refrain from submitting new versions everyday? It is one of the most frowned-upon behavior in the kernel community.
I'm intentionally ignoring v4.
Thanks, dropping it.
Signature · 1 line
An old man doll... just what I always wanted! - Clara