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

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

[Bagas Sanjaya]

Add missing page title for
Documentation/doc-guide/{kernel-doc,sphinx}.rst. Without it, top-level
TOC for doc-guide directly shows chapter headings instead.

Changes since v1 [1]:
  - Split into two patches
  - Promote "Writing kernel-doc comments" (suggested by Jonathan
    Corbet)
  - Use suggested page title from Jonathan Corbet for sphinx.rst

[1]: https://lore.kernel.org/linux-doc/20220322113645.502544-1-bagasdotme@gmail.com/

Bagas Sanjaya (2):
  Documentation: kernel-doc: Promote "Writing kernel-doc comments" to
    page title
  Documentation: sphinx: replace "Introduction" chapter heading with
    page title

 Documentation/doc-guide/kernel-doc.rst | 29 +++++++++++++-------------
 Documentation/doc-guide/sphinx.rst     |  5 +++--
 2 files changed, 18 insertions(+), 16 deletions(-)


base-commit: f443e374ae131c168a065ea1748feac6b2e76613
-- 
An old man doll... just what I always wanted! - Clara

[PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing kernel-doc comments" to page title

[Bagas Sanjaya]

Promote the first heading from chapter heading to page title. While at
it, fix heading inconsistencies by promoting the appropriate headings.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: "Rafael J. Wysocki" <rafael.j.wysocki@intel.com>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: linux-kernel@vger.kernel.org
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/doc-guide/kernel-doc.rst | 29 +++++++++++++-------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 79aaa55d6bcf2b..ea41e05d0e8903 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -1,3 +1,4 @@
+===========================
 Writing kernel-doc comments
 ===========================
 
@@ -31,7 +32,7 @@ kernel source code layout. This is lower priority and at the discretion
 of the maintainer of that kernel source file.
 
 How to format kernel-doc comments
----------------------------------
+=================================
 
 The opening comment mark ``/**`` is used for kernel-doc comments. The
 ``kernel-doc`` tool will extract comments marked this way. The rest of
@@ -56,7 +57,7 @@ requested to perform extra gcc checks::
 	make W=n
 
 Function documentation
-----------------------
+======================
 
 The general format of a function and function-like macro kernel-doc comment is::
 
@@ -88,7 +89,7 @@ ends with an argument description, a blank comment line, or the end of the
 comment block.
 
 Function parameters
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 Each function argument should be described in order, immediately following
 the short function description.  Do not leave a blank line between the
@@ -116,7 +117,7 @@ be written in kernel-doc notation as::
       * @...: description
 
 Function context
-~~~~~~~~~~~~~~~~
+----------------
 
 The context in which a function can be called should be described in a
 section named ``Context``. This should include whether the function
@@ -134,7 +135,7 @@ Examples::
   * Context: Interrupt context.
 
 Return values
-~~~~~~~~~~~~~
+-------------
 
 The return value, if any, should be described in a dedicated section
 named ``Return``.
@@ -166,7 +167,7 @@ named ``Return``.
      effect.
 
 Structure, union, and enumeration documentation
------------------------------------------------
+===============================================
 
 The general format of a struct, union, and enum kernel-doc comment is::
 
@@ -189,7 +190,7 @@ lines, and ends with a member description, a blank comment line, or the
 end of the comment block.
 
 Members
-~~~~~~~
+-------
 
 Members of structs, unions and enums should be documented the same way
 as function parameters; they immediately succeed the short description
@@ -223,7 +224,7 @@ Example::
   };
 
 Nested structs/unions
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 It is possible to document nested structs and unions, like::
 
@@ -274,7 +275,7 @@ It is possible to document nested structs and unions, like::
       should be documented as ``@bar:``
 
 In-line member documentation comments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 The structure members may also be documented in-line within the definition.
 There are two styles, single-line comments where both the opening ``/**`` and
@@ -311,7 +312,7 @@ on a line of their own, like all other kernel-doc comments::
   };
 
 Typedef documentation
----------------------
+=====================
 
 The general format of a typedef kernel-doc comment is::
 
@@ -336,7 +337,7 @@ Typedefs with function prototypes can also be documented::
    typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
 
 Highlights and cross-references
--------------------------------
+===============================
 
 The following special patterns are recognized in the kernel-doc comment
 descriptive text and converted to proper reStructuredText markup and `Sphinx C
@@ -385,7 +386,7 @@ Domain`_ references.
   instead. This is mostly for legacy comments.
 
 Cross-referencing from reStructuredText
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=======================================
 
 No additional syntax is needed to cross-reference the functions and types
 defined in the kernel-doc comments from reStructuredText documents.
@@ -408,7 +409,7 @@ through the following syntax::
 For further details, please refer to the `Sphinx C Domain`_ documentation.
 
 Overview documentation comments
--------------------------------
+===============================
 
 To facilitate having source code and comments close together, you can include
 kernel-doc documentation blocks that are free-form comments instead of being
@@ -524,7 +525,7 @@ source.
 .. _kernel_doc:
 
 How to use kernel-doc to generate man pages
--------------------------------------------
+===========================================
 
 If you just want to use kernel-doc to generate man pages you can do this
 from the kernel git tree::
-- 
An old man doll... just what I always wanted! - Clara

[PATCH v2 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: "Rafael J. Wysocki" <rafael.j.wysocki@intel.com>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: linux-kernel@vger.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 v2 1/2] Documentation: kernel-doc: Promote "Writing kernel-doc comments" to page title

[Mauro Carvalho Chehab]

Em Sat, 26 Mar 2022 19:33:37 +0700
Bagas Sanjaya <bagasdotme@gmail.com> escreveu:

> Promote the first heading from chapter heading to page title. While at
> it, fix heading inconsistencies by promoting the appropriate headings.
> 
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: "David S. Miller" <davem@davemloft.net>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: "Rafael J. Wysocki" <rafael.j.wysocki@intel.com>
> Cc: Jens Axboe <axboe@kernel.dk>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: Akira Yokosawa <akiyks@gmail.com>
> Cc: linux-kernel@vger.kernel.org
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/doc-guide/kernel-doc.rst | 29 +++++++++++++-------------
>  1 file changed, 15 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index 79aaa55d6bcf2b..ea41e05d0e8903 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst
> @@ -1,3 +1,4 @@
> +===========================
>  Writing kernel-doc comments
>  ===========================
>  
> @@ -31,7 +32,7 @@ kernel source code layout. This is lower priority and at the discretion
>  of the maintainer of that kernel source file.
>  
>  How to format kernel-doc comments
> ----------------------------------
> +=================================

Hmm... I can't really see any differences... What this patch seems to be
doing is to just change the markups for each level.

See, on Sphinx, the first markup (whatever it is) is level 1, level 2
the second different markup and so on.

So, before this patch, kernel-doc.rst had:

	level 1: Writing kernel-doc comments
	=====================================

	level 2: How to format kernel-doc comments
	------------------------------------------

	level 3: Function parameters
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~

And after it, it will have:

	====================================
	level 1: Writing kernel-doc comments
	====================================

	level 2: How to format kernel-doc comments
	==========================================

	level 3: Function parameters
	----------------------------

No semantic changes at all.

The only (eventual) value of a change like that would be to make the
levels more uniform, but IMO, it is not worth to apply a change like
that, as:

	1. There are a lot other documents that don't use the more commonly
	   used level standard;

	2. Making all .rst files to use the same definitions is hard;

	3. Even if we place everything using identical markups for every
	   level, as new stuff gets added, different (still valid)
	   markups could be used on newer documents.

Regards,
Mauro


>  
>  The opening comment mark ``/**`` is used for kernel-doc comments. The
>  ``kernel-doc`` tool will extract comments marked this way. The rest of
> @@ -56,7 +57,7 @@ requested to perform extra gcc checks::
>  	make W=n
>  
>  Function documentation
> -----------------------
> +======================
>  
>  The general format of a function and function-like macro kernel-doc comment is::
>  
> @@ -88,7 +89,7 @@ ends with an argument description, a blank comment line, or the end of the
>  comment block.
>  
>  Function parameters
> -~~~~~~~~~~~~~~~~~~~
> +-------------------
>  
>  Each function argument should be described in order, immediately following
>  the short function description.  Do not leave a blank line between the
> @@ -116,7 +117,7 @@ be written in kernel-doc notation as::
>        * @...: description
>  
>  Function context
> -~~~~~~~~~~~~~~~~
> +----------------
>  
>  The context in which a function can be called should be described in a
>  section named ``Context``. This should include whether the function
> @@ -134,7 +135,7 @@ Examples::
>    * Context: Interrupt context.
>  
>  Return values
> -~~~~~~~~~~~~~
> +-------------
>  
>  The return value, if any, should be described in a dedicated section
>  named ``Return``.
> @@ -166,7 +167,7 @@ named ``Return``.
>       effect.
>  
>  Structure, union, and enumeration documentation
> ------------------------------------------------
> +===============================================
>  
>  The general format of a struct, union, and enum kernel-doc comment is::
>  
> @@ -189,7 +190,7 @@ lines, and ends with a member description, a blank comment line, or the
>  end of the comment block.
>  
>  Members
> -~~~~~~~
> +-------
>  
>  Members of structs, unions and enums should be documented the same way
>  as function parameters; they immediately succeed the short description
> @@ -223,7 +224,7 @@ Example::
>    };
>  
>  Nested structs/unions
> -~~~~~~~~~~~~~~~~~~~~~
> +---------------------
>  
>  It is possible to document nested structs and unions, like::
>  
> @@ -274,7 +275,7 @@ It is possible to document nested structs and unions, like::
>        should be documented as ``@bar:``
>  
>  In-line member documentation comments
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +-------------------------------------
>  
>  The structure members may also be documented in-line within the definition.
>  There are two styles, single-line comments where both the opening ``/**`` and
> @@ -311,7 +312,7 @@ on a line of their own, like all other kernel-doc comments::
>    };
>  
>  Typedef documentation
> ----------------------
> +=====================
>  
>  The general format of a typedef kernel-doc comment is::
>  
> @@ -336,7 +337,7 @@ Typedefs with function prototypes can also be documented::
>     typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
>  
>  Highlights and cross-references
> --------------------------------
> +===============================
>  
>  The following special patterns are recognized in the kernel-doc comment
>  descriptive text and converted to proper reStructuredText markup and `Sphinx C
> @@ -385,7 +386,7 @@ Domain`_ references.
>    instead. This is mostly for legacy comments.
>  
>  Cross-referencing from reStructuredText
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +=======================================
>  
>  No additional syntax is needed to cross-reference the functions and types
>  defined in the kernel-doc comments from reStructuredText documents.
> @@ -408,7 +409,7 @@ through the following syntax::
>  For further details, please refer to the `Sphinx C Domain`_ documentation.
>  
>  Overview documentation comments
> --------------------------------
> +===============================
>  
>  To facilitate having source code and comments close together, you can include
>  kernel-doc documentation blocks that are free-form comments instead of being
> @@ -524,7 +525,7 @@ source.
>  .. _kernel_doc:
>  
>  How to use kernel-doc to generate man pages
> --------------------------------------------
> +===========================================
>  
>  If you just want to use kernel-doc to generate man pages you can do this
>  from the kernel git tree::



Thanks,
Mauro

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

[Mauro Carvalho Chehab]

Em Sat, 26 Mar 2022 19:33:38 +0700
Bagas Sanjaya <bagasdotme@gmail.com> escreveu:

> 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: "Rafael J. Wysocki" <rafael.j.wysocki@intel.com>
> Cc: Jens Axboe <axboe@kernel.dk>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: Akira Yokosawa <akiyks@gmail.com>
> Cc: linux-kernel@vger.kernel.org
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

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



Thanks,
Mauro

Re: [PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing kernel-doc comments" to page title

[Bagas Sanjaya]

On 26/03/22 20.56, Mauro Carvalho Chehab wrote:
> Hmm... I can't really see any differences... What this patch seems to be
> doing is to just change the markups for each level.
> 
> See, on Sphinx, the first markup (whatever it is) is level 1, level 2
> the second different markup and so on.
> 
> So, before this patch, kernel-doc.rst had:
> 
> 	level 1: Writing kernel-doc comments
> 	=====================================
> 
> 	level 2: How to format kernel-doc comments
> 	------------------------------------------
> 
> 	level 3: Function parameters
> 	~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 
> And after it, it will have:
> 
> 	====================================
> 	level 1: Writing kernel-doc comments
> 	====================================
> 
> 	level 2: How to format kernel-doc comments
> 	==========================================
> 
> 	level 3: Function parameters
> 	----------------------------
> 
> No semantic changes at all.
> 
> The only (eventual) value of a change like that would be to make the
> levels more uniform, but IMO, it is not worth to apply a change like
> that, as:
> 
> 	1. There are a lot other documents that don't use the more commonly
> 	   used level standard;
> 
> 	2. Making all .rst files to use the same definitions is hard;
> 
> 	3. Even if we place everything using identical markups for every
> 	   level, as new stuff gets added, different (still valid)
> 	   markups could be used on newer documents.
> 
> Regards,
> Mauro
> 

Indeed, fixing heading levels when adding title heading is required because
without it, Sphinx will complain "indentation inconsistency" error.

Maybe better splitting indentation level changes into its own patch, right?

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

Re: [PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing kernel-doc comments" to page title

[Akira Yokosawa]

Hello Bagas,

On Sun, 27 Mar 2022 12:27:20 +0700,
Bagas Sanjaya wrote:
> On 26/03/22 20.56, Mauro Carvalho Chehab wrote:
>> Hmm... I can't really see any differences... What this patch seems to be
>> doing is to just change the markups for each level.
>>
>> See, on Sphinx, the first markup (whatever it is) is level 1, level 2
>> the second different markup and so on.
>>
>> So, before this patch, kernel-doc.rst had:
>>
>>     level 1: Writing kernel-doc comments
>>     =====================================
>>
>>     level 2: How to format kernel-doc comments
>>     ------------------------------------------
>>
>>     level 3: Function parameters
>>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>
>> And after it, it will have:
>>
>>     ====================================
>>     level 1: Writing kernel-doc comments
>>     ====================================
>>
>>     level 2: How to format kernel-doc comments
>>     ==========================================
>>
>>     level 3: Function parameters
>>     ----------------------------
>>
>> No semantic changes at all.
>>
>> The only (eventual) value of a change like that would be to make the
>> levels more uniform, but IMO, it is not worth to apply a change like
>> that, as:
>>
>>     1. There are a lot other documents that don't use the more commonly
>>        used level standard;
>>
>>     2. Making all .rst files to use the same definitions is hard;
>>
>>     3. Even if we place everything using identical markups for every
>>        level, as new stuff gets added, different (still valid)
>>        markups could be used on newer documents.
>>
>> Regards,
>> Mauro
>>
> 
> Indeed, fixing heading levels when adding title heading is required because
> without it, Sphinx will complain "indentation inconsistency" error.

I think all you'd need to do would be to promote both of two headings
of

    Title A
    =======

to

    =======
    Title A
    =======

, namely "Writing kernel-doc comments" and "Including kernel-doc
comments".  They deserve their own chapters in PDF.

As Mauro says, such changes won't have any effect on the resulting
pretty-printed docs.  So I'm afraid I don't see any point in 1/2.

        Thanks, Akira

> 
> Maybe better splitting indentation level changes into its own patch, right?
>