lkml.org 
[lkml]   [2022]   [Mar]   [25]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
From
SubjectRe: [PATCH RESEND] Documentation: add missing page title for kernel-doc.rst and sphinx.rst
Date
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

\
 
 \ /
  Last update: 2022-09-17 16:19    [W:0.043 / U:1.900 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site