* [PATCH v4 0/2] Documentation: doc-guide: Add missing page titles
@ 2022-03-29 4:52 Bagas Sanjaya
2022-03-29 4:52 ` [PATCH v4 1/2] Documentation: kernel-doc: Promote two chapter headings to page title Bagas Sanjaya
` (2 more replies)
0 siblings, 3 replies; 4+ messages in thread
From: Bagas Sanjaya @ 2022-03-29 4:52 UTC (permalink / raw)
To: linux-doc
Cc: Bagas Sanjaya, Jonathan Corbet, David S. Miller,
Greg Kroah-Hartman, Tony Nguyen, Vinod Koul, Daniel Borkmann,
Mauro Carvalho Chehab, Akira Yokosawa, Rafael J. Wysocki,
Jens Axboe, linux-kernel
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* [PATCH v4 1/2] Documentation: kernel-doc: Promote two chapter headings to page title
2022-03-29 4:52 [PATCH v4 0/2] Documentation: doc-guide: Add missing page titles Bagas Sanjaya
@ 2022-03-29 4:52 ` Bagas Sanjaya
2022-03-29 4:52 ` [PATCH v4 2/2] Documentation: sphinx: replace "Introduction" chapter heading with " Bagas Sanjaya
2022-04-05 16:04 ` [PATCH v4 0/2] Documentation: doc-guide: Add missing page titles Jonathan Corbet
2 siblings, 0 replies; 4+ messages in thread
From: Bagas Sanjaya @ 2022-03-29 4:52 UTC (permalink / raw)
To: linux-doc
Cc: Bagas Sanjaya, Jonathan Corbet, David S. Miller,
Greg Kroah-Hartman, Tony Nguyen, Vinod Koul, Daniel Borkmann,
Mauro Carvalho Chehab, Akira Yokosawa, Rafael J. Wysocki,
Jens Axboe, linux-kernel
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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [PATCH v4 2/2] Documentation: sphinx: replace "Introduction" chapter heading with page title
2022-03-29 4:52 [PATCH v4 0/2] Documentation: doc-guide: Add missing page titles Bagas Sanjaya
2022-03-29 4:52 ` [PATCH v4 1/2] Documentation: kernel-doc: Promote two chapter headings to page title Bagas Sanjaya
@ 2022-03-29 4:52 ` Bagas Sanjaya
2022-04-05 16:04 ` [PATCH v4 0/2] Documentation: doc-guide: Add missing page titles Jonathan Corbet
2 siblings, 0 replies; 4+ messages in thread
From: Bagas Sanjaya @ 2022-03-29 4:52 UTC (permalink / raw)
To: linux-doc
Cc: Bagas Sanjaya, Jonathan Corbet, David S. Miller,
Greg Kroah-Hartman, Tony Nguyen, Vinod Koul, Daniel Borkmann,
Mauro Carvalho Chehab, Akira Yokosawa, Rafael J. Wysocki,
Jens Axboe, linux-kernel
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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH v4 0/2] Documentation: doc-guide: Add missing page titles
2022-03-29 4:52 [PATCH v4 0/2] Documentation: doc-guide: Add missing page titles Bagas Sanjaya
2022-03-29 4:52 ` [PATCH v4 1/2] Documentation: kernel-doc: Promote two chapter headings to page title Bagas Sanjaya
2022-03-29 4:52 ` [PATCH v4 2/2] Documentation: sphinx: replace "Introduction" chapter heading with " Bagas Sanjaya
@ 2022-04-05 16:04 ` Jonathan Corbet
2 siblings, 0 replies; 4+ messages in thread
From: Jonathan Corbet @ 2022-04-05 16:04 UTC (permalink / raw)
To: Bagas Sanjaya, linux-doc
Cc: Bagas Sanjaya, David S. Miller, Greg Kroah-Hartman, Tony Nguyen,
Vinod Koul, Daniel Borkmann, Mauro Carvalho Chehab,
Akira Yokosawa, Rafael J. Wysocki, Jens Axboe, linux-kernel
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
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2022-04-05 23:52 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-03-29 4:52 [PATCH v4 0/2] Documentation: doc-guide: Add missing page titles Bagas Sanjaya
2022-03-29 4:52 ` [PATCH v4 1/2] Documentation: kernel-doc: Promote two chapter headings to page title Bagas Sanjaya
2022-03-29 4:52 ` [PATCH v4 2/2] Documentation: sphinx: replace "Introduction" chapter heading with " Bagas Sanjaya
2022-04-05 16:04 ` [PATCH v4 0/2] Documentation: doc-guide: Add missing page titles Jonathan Corbet
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).