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

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

[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 <corbet@lwn.net>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: linux-kernel@vger.kernel.org
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/doc-guide/kernel-doc.rst | 4 ++++
 Documentation/doc-guide/sphinx.rst     | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 79aaa55d6bcf2b..de47b20c806acf 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -1,3 +1,7 @@
+==========================
+kernel-doc Comments Format
+==========================
+
 Writing kernel-doc comments
 ===========================
 
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index bb36f18ae9ac3e..140507de5a85e0 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -1,5 +1,9 @@
 .. _sphinxdoc:
 
+=============
+Sphinx Primer
+=============
+
 Introduction
 ============
 

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

Re: [PATCH RESEND] Documentation: add missing page title for kernel-doc.rst and sphinx.rst

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> 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 <corbet@lwn.net>
> Cc: "David S. Miller" <davem@davemloft.net>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: linux-kernel@vger.kernel.org
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/doc-guide/kernel-doc.rst | 4 ++++
>  Documentation/doc-guide/sphinx.rst     | 4 ++++
>  2 files changed, 8 insertions(+)
>
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index 79aaa55d6bcf2b..de47b20c806acf 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst
> @@ -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.

> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index bb36f18ae9ac3e..140507de5a85e0 100644
> --- a/Documentation/doc-guide/sphinx.rst
> +++ b/Documentation/doc-guide/sphinx.rst
> @@ -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

Re: [PATCH RESEND] Documentation: add missing page title for kernel-doc.rst and sphinx.rst

[Bagas Sanjaya]

On 26/03/22 02.29, Jonathan Corbet wrote:
>> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
>> index 79aaa55d6bcf2b..de47b20c806acf 100644
>> --- a/Documentation/doc-guide/kernel-doc.rst
>> +++ b/Documentation/doc-guide/kernel-doc.rst
>> @@ -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.
> 

OK.

>> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
>> index bb36f18ae9ac3e..140507de5a85e0 100644
>> --- a/Documentation/doc-guide/sphinx.rst
>> +++ b/Documentation/doc-guide/sphinx.rst
>> @@ -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?
> 

I agree with your document title suggestion.

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