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

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

[Bagas Sanjaya]

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

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

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 v3 1/2] Documentation: kernel-doc: Promote two chapter headings to page title

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

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
Suggested-by: Akira Yokosawa <akiyks@gmail.com>
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

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

[Akira Yokosawa]

On Mon, 28 Mar 2022 13:50:30 +0700,
Bagas Sanjaya wrote:
> 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!

> 
> 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
> Suggested-by: Akira Yokosawa <akiyks@gmail.com>

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

        Thanks, Akira

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

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

[Bagas Sanjaya]

On 28/03/22 14.46, Akira Yokosawa wrote:
> On Mon, 28 Mar 2022 13:50:30 +0700,
> Bagas Sanjaya wrote:
>> 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!
> 

My intention is to give page title for kernel-doc.rst, according to
documentation guideline at [1].

>>
>> 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
>> Suggested-by: Akira Yokosawa <akiyks@gmail.com>
> 
> Please don't put this Suggested-by: at the moment.
> 
>          Thanks, Akira
> 

OK, will drop the trailer.

-- 
An old man doll... just what I always wanted! - Clara

[PATCH v3 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