Skip to contentSkip to conversation

Documentation: add missing page title for kernel-doc.rst and sphinx.rst

PATCH RESEND In review Bagas Sanjaya 2 participants 3 messages Mar 22, 2022 – Mar 26, 2022 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH RESEND 1/1 Documentation: add missing page title for kernel-doc.rst and sphinx.rst

sphinx.rst and kernel-doc.rst are missing page title, thus top-level headings in the respective documentation is displayed in the table of contents for doc-guide.

Add the title.

Cc Jonathan Corbet <[email protected]>
Cc "David S. Miller" <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>
Cc Mauro Carvalho Chehab <[email protected]>
---
 Documentation/doc-guide/kernel-doc.rst | 4 ++++
 Documentation/doc-guide/sphinx.rst     | 4 ++++
 2 files changed, 8 insertions(+)
Documentation/doc-guide/kernel-doc.rst +4 -0
index 79aaa55d6bcf2b..de47b20c806acf 100644
@@ -1,3 +1,7 @@
+==========================
+kernel-doc Comments Format
+==========================
+
 Writing kernel-doc comments
 ===========================
 
Documentation/doc-guide/sphinx.rst +4 -0
index bb36f18ae9ac3e..140507de5a85e0 100644
@@ -1,5 +1,9 @@
 .. _sphinxdoc:
 
+=============
+Sphinx Primer
+=============
+
 Introduction
 ============
 

base-commit: 09688c0166e76ce2fb85e86b9d99be8b0084cdf9

Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer
#1 lore raw
Quoted 22 lines · Bagas Sanjaya

sphinx.rst and kernel-doc.rst are missing page title, thus top-level headings in the respective documentation is displayed in the table of contents for doc-guide.

Add the title.

Cc Jonathan Corbet <[email protected]>
Cc "David S. Miller" <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>
Cc Mauro Carvalho Chehab <[email protected]>
---
 Documentation/doc-guide/kernel-doc.rst | 4 ++++
 Documentation/doc-guide/sphinx.rst     | 4 ++++
 2 files changed, 8 insertions(+)
Documentation/doc-guide/kernel-doc.rst +0 -0
index 79aaa55d6bcf2b..de47b20c806acf 100644

Documentation/doc-guide/kernel-doc.rst line 6

Quoted 6 lines
Documentation/doc-guide/kernel-doc.rst +4 -0
@@ -1,3 +1,7 @@
+==========================
+kernel-doc Comments Format
+==========================
+
 Writing kernel-doc comments
 ===========================

Honestly, I think this is better fixed just by promoting the existing heading up a level. It describes the file nicely, and we don't need two headers there.

Documentation/doc-guide/sphinx.rst line 8

Quoted 13 lines
Documentation/doc-guide/sphinx.rst +4 -0
index bb36f18ae9ac3e..140507de5a85e0 100644
@@ -1,5 +1,9 @@
 .. _sphinxdoc:
 
+=============
+Sphinx Primer
+=============
+
 Introduction
 ============

Here, perhaps, replace "Introduction" with "Using Sphinx for kernel documentation" or some such and make that the document title?

Thanks,

jon

#2 lore raw
Quoted 7 lines · Jonathan Corbet
Quoted 7 lines
Documentation/doc-guide/kernel-doc.rst +2 -0
index 79aaa55d6bcf2b..de47b20c806acf 100644
@@ -1,3 +1,7 @@
+==========================
+kernel-doc Comments Format
Quoted 9 lines

Documentation/doc-guide/kernel-doc.rst line 6

Quoted 4 lines
Documentation/doc-guide/kernel-doc.rst +2 -0
+==========================
+
  Writing kernel-doc comments
  ===========================

Honestly, I think this is better fixed just by promoting the existing heading up a level. It describes the file nicely, and we don't need two headers there.

OK.

Quoted 7 lines
Quoted 7 lines
Documentation/doc-guide/sphinx.rst +0 -0
index bb36f18ae9ac3e..140507de5a85e0 100644
@@ -1,5 +1,9 @@
  .. _sphinxdoc:
 
Quoted 10 lines

Documentation/doc-guide/sphinx.rst line 8

Quoted 6 lines
Documentation/doc-guide/sphinx.rst +4 -0
+=============
+Sphinx Primer
+=============
+
  Introduction
  ============

Here, perhaps, replace "Introduction" with "Using Sphinx for kernel documentation" or some such and make that the document title?

I agree with your document title suggestion.

Signature · 1 line
An old man doll... just what I always wanted! - Clara