Skip to contentSkip to conversation

Documentation: doc-guide: Add missing page titles

PATCH In review Bagas Sanjaya 2 participants 4 messages Mar 29, 2022 – Apr 5, 2022 Documentation

lore
Share & tools
lore
#0 lore raw

v4 cover Documentation: doc-guide: Add missing page titles

The kernel documentation guidelines [1] lists that there should have page title.

Add missing page title for kernel-doc.rst and sphinx.rst, in accordance to the guideline.

Changes since v3 [2]:
- Clarify that there is no output differences except formatting

    semantics in [1/2]

- Drop Suggested-by trailer from Akira Yokosawa in [1/2]

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

[1]: https://docs.kernel.org/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation
[2]:
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
#1 lore raw

PATCH v4 1/2 Documentation: kernel-doc: Promote two chapter headings to page title

Promote "Writing kernel-doc comments" heading to page title, in accordance to kernel documentation guidelines. Also promote "Including kernel-doc comments" heading because both headings deserve their own chapters in PDF output.

There is no differences in the resulting output except formatting semantics.

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

PATCH v4 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
maintainer
#3 lore raw
In reply to Bagas Sanjaya
Quoted 15 lines · Bagas Sanjaya

The kernel documentation guidelines [1] lists that there should have page title.

Add missing page title for kernel-doc.rst and sphinx.rst, in accordance to the guideline.

Changes since v3 [2]:
- Clarify that there is no output differences except formatting

    semantics in [1/2]

- Drop Suggested-by trailer from Akira Yokosawa in [1/2]

[1]: https://docs.kernel.org/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation
[2]:
https://lore.kernel.org/linux-doc/[email protected]/

Quoted 8 lines

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

OK, I think this improves the situation overall, so I've applied these, thanks.

jon