[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

[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

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

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

[Akira Yokosawa]

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

On Mon, 28 Mar 2022 19:28:51 +0700,
Bagas Sanjaya wrote:
> 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].

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

> 
[...]

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

[Bagas Sanjaya]

On 29/03/22 15.25, Akira Yokosawa wrote:
> [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.
> 

Thanks, dropping it.

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