Documentation: doc-guide: Add missing page titles
v4 cover Documentation: doc-guide: Add missing page titles
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/[email protected]/
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
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH v4 1/2 Documentation: kernel-doc: Promote two chapter headings to page title
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.
--- Documentation/doc-guide/kernel-doc.rst | 2 ++ 1 file changed, 2 insertions(+)
Documentation/doc-guide/kernel-doc.rst +2 -0
@@ -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 =============================
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH v4 2/2 Documentation: sphinx: replace "Introduction" chapter heading with page title
In reply to Bagas SanjayaReplace 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.
--- Documentation/doc-guide/sphinx.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/doc-guide/sphinx.rst +3 -2
@@ -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
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Jonathan Corbet
maintainerQuoted 15 lines · Bagas Sanjaya
The kernel documentation guidelines [1] lists that there should have page title.
Add missing page title for
kernel-doc.rstandsphinx.rst, in accordance to the guideline.Changes since v3 [2]:
- Clarify that there is no output differences except formattingsemantics 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/[email protected]/
Quoted 8 lines
Bagas Sanjaya (2):
Documentation: kernel-doc: Promote two chapter headings to page title
Documentation: sphinx: replace "Introduction" chapter heading with
page titleDocumentation/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