[PATCH v4 0/2] Documentation: doc-guide: Add missing page titles

[PATCH v4 0/2] Documentation: doc-guide: Add missing page titles

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

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Tony Nguyen <anthony.l.nguyen@intel.com>
Cc: Vinod Koul <vkoul@kernel.org>
Cc: Daniel Borkmann <daniel@iogearbox.net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: "Rafael J. Wysocki" <rafael.j.wysocki@intel.com>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: linux-kernel@vger.kernel.org

[1]: https://docs.kernel.org/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation
[2]:
https://lore.kernel.org/linux-doc/20220328065030.24936-1-bagasdotme@gmail.com/

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
-- 
An old man doll... just what I always wanted! - Clara

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

[Bagas Sanjaya]

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 <corbet@lwn.net>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Tony Nguyen <anthony.l.nguyen@intel.com>
Cc: Vinod Koul <vkoul@kernel.org>
Cc: Daniel Borkmann <daniel@iogearbox.net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: "Rafael J. Wysocki" <rafael.j.wysocki@intel.com>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: linux-kernel@vger.kernel.org
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/doc-guide/kernel-doc.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 79aaa55d6bcf2b..a7cb2afd799007 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -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
 =============================
 
-- 
An old man doll... just what I always wanted! - Clara

[PATCH v4 2/2] Documentation: sphinx: replace "Introduction" chapter heading with page title

[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 <corbet@lwn.net>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Tony Nguyen <anthony.l.nguyen@intel.com>
Cc: Vinod Koul <vkoul@kernel.org>
Cc: Daniel Borkmann <daniel@iogearbox.net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: "Rafael J. Wysocki" <rafael.j.wysocki@intel.com>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: linux-kernel@vger.kernel.org
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/doc-guide/sphinx.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index bb36f18ae9ac3e..2ff1ab4158d48e 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -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
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v4 0/2] Documentation: doc-guide: Add missing page titles

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> 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/20220328065030.24936-1-bagasdotme@gmail.com/
>
> 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