Skip to contentSkip to conversation

Documentation: doc-guide: Add missing page titles

PATCH Superseded Bagas Sanjaya 2 participants 7 messages Mar 28, 2022 – Mar 29, 2022 Documentation

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

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

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

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
#1 lore raw

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.

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]>
---
 Documentation/doc-guide/kernel-doc.rst | 2 ++
 1 file changed, 2 insertions(+)
Documentation/doc-guide/kernel-doc.rst +2 -0
index 79aaa55d6bcf2b..a7cb2afd799007 100644
@@ -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
#6 lore raw

PATCH v3 2/2 Documentation: sphinx: replace "Introduction" chapter heading with page title

In reply to Bagas Sanjaya

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

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]>
---
 Documentation/doc-guide/sphinx.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/doc-guide/sphinx.rst +3 -2
index bb36f18ae9ac3e..2ff1ab4158d48e 100644
@@ -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
#2 lore raw

Re: [PATCH v3 1/2] Documentation: kernel-doc: Promote two chapter headings to page title

In reply to Bagas Sanjaya
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*.

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

Please don't put this Suggested-by: at the moment.

Thanks, Akira

Quoted 22 lines
---
 Documentation/doc-guide/kernel-doc.rst | 2 ++
 1 file changed, 2 insertions(+)
Documentation/doc-guide/kernel-doc.rst +2 -0
index 79aaa55d6bcf2b..a7cb2afd799007 100644
@@ -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
 =============================
 
#3 lore raw

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]>
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
#4 lore raw

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.

See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#don-t-get-discouraged-or-impatient

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

[...]

#5 lore raw

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.

See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#don-t-get-discouraged-or-impatient

I'm intentionally ignoring v4.

Thanks, dropping it.

Signature · 1 line
An old man doll... just what I always wanted! - Clara