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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87v8w1esqg.fsf@meer.lwn.net>
Date:   Fri, 25 Mar 2022 13:29:11 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Bagas Sanjaya <bagasdotme@...il.com>, linux-doc@...r.kernel.org
Cc:     Bagas Sanjaya <bagasdotme@...il.com>,
        "David S. Miller" <davem@...emloft.net>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH RESEND] Documentation: add missing page title for
 kernel-doc.rst and sphinx.rst

Bagas Sanjaya <bagasdotme@...il.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@....net>
> Cc: "David S. Miller" <davem@...emloft.net>
> Cc: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> Cc: linux-kernel@...r.kernel.org
> Signed-off-by: Bagas Sanjaya <bagasdotme@...il.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