From nobody Wed Apr 29 09:33:15 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9A7C8CCA473 for ; Thu, 9 Jun 2022 13:23:41 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1343766AbiFINXj (ORCPT ); Thu, 9 Jun 2022 09:23:39 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42982 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S245054AbiFINXe (ORCPT ); Thu, 9 Jun 2022 09:23:34 -0400 Received: from mail-pg1-x536.google.com (mail-pg1-x536.google.com [IPv6:2607:f8b0:4864:20::536]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 806882600; Thu, 9 Jun 2022 06:23:33 -0700 (PDT) Received: by mail-pg1-x536.google.com with SMTP id d129so21806768pgc.9; Thu, 09 Jun 2022 06:23:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:date:mime-version:user-agent:subject:content-language:to :cc:references:from:in-reply-to:content-transfer-encoding; bh=+YkdE4hgL9nudEqBz5hZQ0msyQAME4oIXjwpc7HKTC4=; b=kSLcdlt+IN5JIBnJAeI9HUaw3v+tFe11y6pKaRx+W+JMBoNlQEfYvNyH3QWBzC3hQZ /FQfM+NN+dQC50RZW8QaG7gYa9LfyDjqCercchn4qONMAz/FScyoeZ1wsBgYD7+Io6Wr oelsqYApYfG3r+dcjopj2SolZNdcp9pK9zqqhSfcY7C/3iFqfIi0tVCFZQIG4CTNUnqc ASsA0Ds+gfQxTT4NjQRXNu6EupkB2lcdORW68vR2sFPuf7YMyKfkQRwD+TjsWFHPZn9V 41r480kar8I3HEbHcrdd1KvthfxSX2hwg/3YE5Zlb8wh7emejC8YRGWqOX5l13BEfXym 2m8A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:date:mime-version:user-agent:subject :content-language:to:cc:references:from:in-reply-to :content-transfer-encoding; bh=+YkdE4hgL9nudEqBz5hZQ0msyQAME4oIXjwpc7HKTC4=; b=56AKyi6QVnbcairB7MAZ4+b6lWJlgpF6C4kktqJJeWPwUZQDeCsUSne3GcfcjO0SkO JOCT+csuCPT7UGhkoZ/5T8R/51IGfSDh4pdgneptDBB1wHeZEaTaeotLgpQ9QjXHx9d0 QL4KS9Z/h1NFQz2k36hQR8GKfNsAArUF6S7et87vEQLtMcQnRpCavpdVvPLmByZAoWv0 Qk+e/+apawd2f6nnG6ZGvkaidniKC6bVcpHNYxICd6SC7wYx4Mu9LgRUu/TuuCI7ZMUz 4EB8frxV/GB8WhLUgVi82gOhKKAPLBDfpEpabce2MVE/uBlK30Vx92ClymoYmg/JtAns sPZA== X-Gm-Message-State: AOAM533xsUTRr+0DTg8LyLGT+FO0aVHhKOYdudNE3PBfIuhbB++UG/BQ KHzCJspcQ+RdZ2dgAQ+z/nw= X-Google-Smtp-Source: ABdhPJyMOFMlhAynmsJzHw50MAGtr8ty3qmRrNgcjKI3OM2dTXIg01V2FcUu4QCq1unNbC/t1pS8KA== X-Received: by 2002:a05:6a00:1387:b0:51c:2712:7859 with SMTP id t7-20020a056a00138700b0051c27127859mr19074541pfg.38.1654781013066; Thu, 09 Jun 2022 06:23:33 -0700 (PDT) Received: from [192.168.11.5] (KD106167171201.ppp-bb.dion.ne.jp. [106.167.171.201]) by smtp.gmail.com with ESMTPSA id a21-20020a170902ee9500b00161a40b2135sm16914849pld.104.2022.06.09.06.23.30 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 09 Jun 2022 06:23:32 -0700 (PDT) Message-ID: <81cddbde-bc28-bec1-fca4-3c8fe2df502f@gmail.com> Date: Thu, 9 Jun 2022 22:23:27 +0900 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.9.1 Subject: [PATCH 1/5] docs/doc-guide: Add footnote on Inkscape for better images in PDF documents Content-Language: en-US To: Jonathan Corbet , linux-doc@vger.kernel.org Cc: Mauro Carvalho Chehab , "Maciej W. Rozycki" , Miguel Ojeda , linux-kernel@vger.kernel.org, Akira Yokosawa References: From: Akira Yokosawa In-Reply-To: Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" With kernel releases v5.18 and later, if you have Inkscape, images embedded in PDF documents are of vector graphics, not the raster images as are the case with pre-v5.18 releases. Even with pre-5.18 releases, having Inkscape would improve images converted from some of SVG files which are not fully covered by the limited capability of rsvg-convert(1) [1]. Add a footnote mentioning the expected improvements of such images. Link: https://gitlab.gnome.org/GNOME/librsvg#non-goals-of-librsvg [1] Signed-off-by: Akira Yokosawa --- Documentation/doc-guide/sphinx.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/s= phinx.rst index 2ff1ab4158d4..edc4fa023986 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -132,7 +132,8 @@ format-specific subdirectories under ``Documentation/ou= tput``. To generate documentation, Sphinx (``sphinx-build``) must obviously be installed. For prettier HTML output, the Read the Docs Sphinx theme (``sphinx_rtd_theme``) is used if available. For PDF output you'll also ne= ed -``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.o= rg). +``XeLaTeX`` and ``convert(1)`` from ImageMagick +(https://www.imagemagick.org).\ [#ink]_ All of these are widely available and packaged in distributions. =20 To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make @@ -152,6 +153,10 @@ The Sphinx theme can be overridden by using the ``DOCS= _THEME`` make variable. =20 To remove the generated documentation, run ``make cleandocs``. =20 +.. [#ink] Having ``inkscape(1)`` from Inkscape (https://inkscape.org) + as well would improve the quality of images embedded in PDF + documents, especially for kernel releases 5.18 and later. + Writing Documentation =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.25.1 From nobody Wed Apr 29 09:33:15 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7FE34C433EF for ; Thu, 9 Jun 2022 13:25:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S237623AbiFINZL (ORCPT ); Thu, 9 Jun 2022 09:25:11 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49888 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1343868AbiFINZG (ORCPT ); Thu, 9 Jun 2022 09:25:06 -0400 Received: from mail-pj1-x1036.google.com (mail-pj1-x1036.google.com [IPv6:2607:f8b0:4864:20::1036]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C96FB152BB2; Thu, 9 Jun 2022 06:25:03 -0700 (PDT) Received: by mail-pj1-x1036.google.com with SMTP id u12-20020a17090a1d4c00b001df78c7c209so26681600pju.1; Thu, 09 Jun 2022 06:25:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:date:mime-version:user-agent:subject:content-language:to :cc:references:from:in-reply-to:content-transfer-encoding; bh=+QrEfwNyUObZpg4FR+sDjlTmpv+zGn+vrSq3i8QmgIA=; b=KjljSREzL0wSolOtkUlpNwONHUFbpDBeP4bOEVdzkt7/LC+m0uNQ952f84SvOUHVuN bMD7CDu5uh2CMmetkp8JZR+W/2B5oNX6TX4koHVCBkolsJkCkxzquLgmLdfYXRp/8TAd CuCO8abxzcObs0NX31sjtO6YZc4FtEPkOcpbeS+dEVA0PR9ECTg9QYihqMurlTSsZUgz nGiu3dc+PalMt9Uf2UfpkBbDsHpSum7BdqTLV8OJWN4vyGUcQlZAQ77z0jJFunrQ6Aao OGvxqAPnh3BNEoWDZ9UmymrKJsIW3IlRdC7xpY1uJg6QASP57GEOxro2NRBvcuCweXGY 7P1g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:date:mime-version:user-agent:subject :content-language:to:cc:references:from:in-reply-to :content-transfer-encoding; bh=+QrEfwNyUObZpg4FR+sDjlTmpv+zGn+vrSq3i8QmgIA=; b=AZ3NN2irCrrh2m8IOaVFX1Yf2ztpB5fROI9ZnaOaj0H1O9n3j0hMZjVEYx11aWSsiJ 7Z6lAKJ+xAEQn58OidaqH+hX46/nm0AyqxbEC43EfDWIOkZc8/ZO5kv2JZT3mhDiXfYA 9dQo/78+bgj16hyUFe0ZwerXPw6hxVoh3u9QhsJzTBpKqMRgr8GHR+D6f1ZYiaY8Nioj P3iAGgS0l7WKm9c2kHnWonUGfRl/tu3voSVJXUdPZ2z4vuzrTpSurpaJ8yJnwps5gwut ezfUtNXzpg3kqq+BxQ8MK3pASseBaPva6N1UV1UxxT81M1SKFMJcY0FHVeo/MeVHz0SF /uKA== X-Gm-Message-State: AOAM533swU1KKvwU2rqc2TKKhJ5c/5mXGCkehPj+2xwP3N4OmS5HcqrQ EPvxRcXOOOeoRP+XNmK9nB0lxi8o2II= X-Google-Smtp-Source: ABdhPJwsevakWlOrt4ajIp6BMcqWo0rbDiVYcTI3fI1UWc0KtcPGoRi7pihMy42NUg8+RwLL19mXhQ== X-Received: by 2002:a17:90b:4c4e:b0:1e3:368b:c09c with SMTP id np14-20020a17090b4c4e00b001e3368bc09cmr3466584pjb.140.1654781103319; Thu, 09 Jun 2022 06:25:03 -0700 (PDT) Received: from [192.168.11.5] (KD106167171201.ppp-bb.dion.ne.jp. [106.167.171.201]) by smtp.gmail.com with ESMTPSA id t15-20020a17090340cf00b0016168e90f2csm16596512pld.208.2022.06.09.06.25.00 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 09 Jun 2022 06:25:02 -0700 (PDT) Message-ID: Date: Thu, 9 Jun 2022 22:24:58 +0900 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.9.1 Subject: [PATCH 2/5] docs/doc-guide: Mention make variable SPHINXDIRS Content-Language: en-US To: Jonathan Corbet , linux-doc@vger.kernel.org Cc: Mauro Carvalho Chehab , "Maciej W. Rozycki" , Miguel Ojeda , linux-kernel@vger.kernel.org, Akira Yokosawa References: From: Akira Yokosawa In-Reply-To: Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" SPHINXDIRS is useful when you want test builds of only those documents affected by your changes. Mention it in the "Sphinx Build" section. Signed-off-by: Akira Yokosawa Cc: Maciej W. Rozycki --- This change is inspired from correspondence with Maciej [1]. [1]: https://lore.kernel.org/r/f4d40da6-756b-9e75-b867-cc9eedc4b232@gmail.c= om -- Documentation/doc-guide/sphinx.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/s= phinx.rst index edc4fa023986..efcccab68286 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -151,6 +151,10 @@ If the theme is not available, it will fall-back to th= e classic one. =20 The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variab= le. =20 +There is another make variable ``SPHINXDIRS``, which is useful when test +building a subset of documentation. Again, see the documentation section +of ``make help`` for the details. + To remove the generated documentation, run ``make cleandocs``. =20 .. [#ink] Having ``inkscape(1)`` from Inkscape (https://inkscape.org) --=20 2.25.1 From nobody Wed Apr 29 09:33:15 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id C8C1ECCA473 for ; Thu, 9 Jun 2022 13:26:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S238773AbiFIN0h (ORCPT ); Thu, 9 Jun 2022 09:26:37 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56570 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234891AbiFIN0e (ORCPT ); Thu, 9 Jun 2022 09:26:34 -0400 Received: from mail-pj1-x1031.google.com (mail-pj1-x1031.google.com [IPv6:2607:f8b0:4864:20::1031]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BAAFD33EA2; Thu, 9 Jun 2022 06:26:32 -0700 (PDT) Received: by mail-pj1-x1031.google.com with SMTP id u12-20020a17090a1d4c00b001df78c7c209so26685261pju.1; Thu, 09 Jun 2022 06:26:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:date:mime-version:user-agent:subject:content-language:to :cc:references:from:in-reply-to:content-transfer-encoding; bh=ShDYdI8cJz4eKhe2LZx3gBgV6zn8fmqFJsqslddaRT8=; b=BmuptZ+PRTXtGSlYMIwn2u4mFKTReW1Z/1FJI7LJxsf7Mn1VfFfgPde7zSZ3/NhjI0 tf0v4Fk7UXtADlco79KE74hB6yRX6jpQ/bligG8DxftDoIXNaeA2zNGijJ0pGoS2JKVS tMt3IpcyoLV2TpfogRpU8oRpapPDlmK9Gu9og4dLA+9yj1H3VNtbjfAOk6+pxtUJncwb owzN3z4QDuYHd+yel95cYYtep89BA4XSFZVBof4GFtXJaklaoGe5BLM6jzLInlR64PED /sKcz/dkuYhMvAZ9yYyOrulq26yz8MILI4PMV87OVCqdrgKnSeXNPqzoO/NFQPzLSLIm KNRA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:date:mime-version:user-agent:subject :content-language:to:cc:references:from:in-reply-to :content-transfer-encoding; bh=ShDYdI8cJz4eKhe2LZx3gBgV6zn8fmqFJsqslddaRT8=; b=mK7ewL16s4E4P/eL8nSR8jqGFDE/QFQEBE9HaXWtmqXB9DuvwMkkKSDrMcYPgKT7kB FmFEpEsVc2AjFayxt6VzkJ9RJK34zG5+RGXlJJA9Oxk71yxqWZ41zp1LxqHHZ/Dntl/K V/CQaPk/2GVXCL2KmWLTJeMq8EY5LBTaJHJsYxILbsQfJYKt9rGWr+/jT4Zw09/6UxTK Eihp4r1kjrEoY7+DtfQ2oHRbLG/kfWGsghSNHLd3tDstUnDT2+zW9lYB2sqHMBmG9ZxG Km82Qw1GagNI1jVS4p4RwqRw7l2tBmdmJ3VR47ajQLjH5GjqkHHFHMQVWVNQtI48h84j gMtA== X-Gm-Message-State: AOAM531gKDRxLPta7wlKNbxPyZoUp3xz2QNLnz+mIfPSVxPLNyAavglK ITtqUl0dWNRIANhxIsLMTa0= X-Google-Smtp-Source: ABdhPJxPz16UeP1BW5ZLa39ojvoPfNniXTPAI605fb6GHDhmj91YhA0rItyFO3mIoMbFouKiVZwGjA== X-Received: by 2002:a17:90a:778c:b0:1df:56a5:8474 with SMTP id v12-20020a17090a778c00b001df56a58474mr3505689pjk.63.1654781191888; Thu, 09 Jun 2022 06:26:31 -0700 (PDT) Received: from [192.168.11.5] (KD106167171201.ppp-bb.dion.ne.jp. [106.167.171.201]) by smtp.gmail.com with ESMTPSA id i19-20020a17090320d300b00163f8ddf160sm16745441plb.161.2022.06.09.06.26.29 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 09 Jun 2022 06:26:30 -0700 (PDT) Message-ID: <732154bc-aa35-2326-2b64-87b6c4dd02e7@gmail.com> Date: Thu, 9 Jun 2022 22:26:27 +0900 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.9.1 Subject: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments Content-Language: en-US To: Jonathan Corbet , linux-doc@vger.kernel.org Cc: Mauro Carvalho Chehab , "Maciej W. Rozycki" , Miguel Ojeda , linux-kernel@vger.kernel.org, Akira Yokosawa References: From: Akira Yokosawa In-Reply-To: Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" Existing guidelines predate the sub-directory wise document management. Update the guidelines to reflect the current state of affairs. Signed-off-by: Akira Yokosawa Cc: Miguel Ojeda --- Documentation/doc-guide/sphinx.rst | 66 +++++++++++++++++++++++------- 1 file changed, 52 insertions(+), 14 deletions(-) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/s= phinx.rst index efcccab68286..f257c4785607 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -202,34 +202,72 @@ Here are some specific guidelines for the kernel docu= mentation: * Also update the content, not just the formatting, when converting documentation. =20 -* Please stick to this order of heading adornments: +* Please stick to this relative order of section title adornments: =20 - 1. ``=3D`` with overline for document title:: + 1. ``=3D`` with overline for 1st level titles:: =20 - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - Document title - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + 1st level title + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 - 2. ``=3D`` for chapters:: + 2. ``=3D`` for 2nd level titles:: =20 - Chapters - =3D=3D=3D=3D=3D=3D=3D=3D + 2nd level title + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 - 3. ``-`` for sections:: + 3. ``-`` for 3rd level titles:: =20 - Section - ------- + 3rd level title + --------------- =20 - 4. ``~`` for subsections:: + 4. ``~`` for 4th level titles:: =20 - Subsection - ~~~~~~~~~~ + 4th level title + ~~~~~~~~~~~~~~~ =20 Although RST doesn't mandate a specific order ("Rather than imposing a f= ixed number and order of section title adornment styles, the order enforced w= ill be the order as encountered."), having the higher levels the same overall m= akes it easier to follow the documents. =20 + .. note:: + - It is not easy to tell the levels (chapter, section, etc.) of title + adornments in a particular .rst file. A title that appears first in + a .rst file can be at any level of document, chapter, section, or + subsection (or deeper) depending on the file's inclusion depth. + + - The RST language does not have an explicit means to specify a "docum= ent + title". Quote from the RST documentation\ [#rstdoc]_ with minor edi= t: + + *Specifically, there is no way to indicate a document title and + subtitle explicitly in reStructuredText. Instead, a lone top-level + section title can be treated as the document title.* + + In the kernel documentation processing, the first title in a top-lev= el + ``index.rst`` can be considered the document title. In HTML, as each + .html output has its source .rst file, the title which happens to co= me + first is used as the title of the resulting HTML page. + Alternatively, it is possible to specify a page title by using the + directive "title".\ [#rstdirtitle]_ + + - There may be a 2nd or 3rd level adornment at the first title in a .r= st + file. This usage is often seen in .rst files that are derived and + split from a larger .rst file. It is sufficient if relative order is + preserved. + + .. [#rstdoc] https://docutils.sourceforge.io/docs/ref/rst/restructured= text.html#document + .. [#rstdirtitle] https://docutils.sourceforge.io/docs/ref/rst/directi= ves.html#metadata-document-title + + .. warning:: + For existing documents, manually updating title adornments just to meet + these guidelines is not recommended. Such changes can be error-prone = and + may break section hierarchy without being caught by reviewers. They m= ay + be justified if done in conjunction with a section reorganization or + similar. + + It would be appreciated if adjustment of those adornments could be + automated in some way. + * For inserting fixed width text blocks (for code examples, use case examples, etc.), use ``::`` for anything that doesn't really benefit from syntax highlighting, especially short snippets. Use --=20 2.25.1 From nobody Wed Apr 29 09:33:15 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E92FBC433EF for ; Thu, 9 Jun 2022 13:27:42 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1343721AbiFIN1k (ORCPT ); Thu, 9 Jun 2022 09:27:40 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:33384 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1343670AbiFIN1g (ORCPT ); Thu, 9 Jun 2022 09:27:36 -0400 Received: from mail-pl1-x62b.google.com (mail-pl1-x62b.google.com [IPv6:2607:f8b0:4864:20::62b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B11B0110988; Thu, 9 Jun 2022 06:27:33 -0700 (PDT) Received: by mail-pl1-x62b.google.com with SMTP id r1so3000272plo.10; Thu, 09 Jun 2022 06:27:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:date:mime-version:user-agent:subject:content-language:to :cc:references:from:in-reply-to:content-transfer-encoding; bh=/w33OC2nKB0l49BpBE16Q95GGKplWgpgkQkpZKKx9XU=; b=Saf2DH6GH3ZFWu6ilc7JhttO6h1rIVxm8yxUGdYoDGgSyY6z8OBBwyX19KwLSOFYTt 1b1aqBlem3FP97Fq0+HTBc4aMncTJJHLVuTHrvqLlfNQPoud3iyEkR3N/I0Joabdv841 UBAxZw7KU9ZhPlwqLi3qxK+FwSVFoCVNXo5Grn7Qt1eGtgxbEHfs1cGXna5kZQXIuf1J mNIdewOE8McOsy0Q0k4xFherTtf0Kj6UdANdGHflT9rK7qyJd+/M/8Ouaz4l0hWRlLtp jr45ETHGXprdUiTDCWzosZtC/qmKG0lu7J6YTYjgV+VBE+A7lrjvaQPBQp7HOaGkm5Pf kkzA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:date:mime-version:user-agent:subject :content-language:to:cc:references:from:in-reply-to :content-transfer-encoding; bh=/w33OC2nKB0l49BpBE16Q95GGKplWgpgkQkpZKKx9XU=; b=o25gjnyNJvF+uVGdcJQwA3L2skq/EY20uspHNJMyZWZGuP7Yh0E0a8HaWeGMFWQONZ 1FdDHP7+Y/LbGo1q2RERSPT5RmZ/XDLmJJ2xe0zIo14HyOr8LCTvnXYck4CdEcNMxen3 CYdwTIbUtcuW9mvlJZpTvo/quXU8IKf0cJ9atFJUbjdGr4gwvF8boCsrEcXERR7EiRUQ 5Y0j774AlEnnyvqW87WvqwNfFopE727+lDsGJkAPHAmRsEzWO/Nw5qTzsurDJTmde2gX besxx+1lcu5D7tKc8Rd78EBW6AcT+nPyU5VGHYqB7HPbWmfXxbPTcJ91ZI9Li239n2fo x3Iw== X-Gm-Message-State: AOAM533+LLsjiVzzm1rT2cYYr0sjKhAitKmMixbwssaZiBN0lmRMt1SF lEIoswPQOrVbQn7kkPVs1kA= X-Google-Smtp-Source: ABdhPJyzZwTxrKl6bUcnX4/gvAWipAyf49NA3Zu5vDclNm8uqtyLx1279BiLXP9/GjSMUPsOKKoEJQ== X-Received: by 2002:a17:902:b215:b0:165:7bdd:a9f1 with SMTP id t21-20020a170902b21500b001657bdda9f1mr40101997plr.41.1654781253192; Thu, 09 Jun 2022 06:27:33 -0700 (PDT) Received: from [192.168.11.5] (KD106167171201.ppp-bb.dion.ne.jp. [106.167.171.201]) by smtp.gmail.com with ESMTPSA id q17-20020a656851000000b003f5d7f0ad6asm17809441pgt.48.2022.06.09.06.27.30 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 09 Jun 2022 06:27:32 -0700 (PDT) Message-ID: <42600ccb-8cfd-434e-cb4f-f871fd8de708@gmail.com> Date: Thu, 9 Jun 2022 22:27:27 +0900 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.9.1 Subject: [RFC PATCH 4/5] docs/doc-guide: Pull guidelines for title adornments out into subsection Content-Language: en-US To: Jonathan Corbet , linux-doc@vger.kernel.org Cc: Mauro Carvalho Chehab , "Maciej W. Rozycki" , Miguel Ojeda , linux-kernel@vger.kernel.org, Akira Yokosawa References: From: Akira Yokosawa In-Reply-To: Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" As it becomes too large as an item in bullet lists, make it a subsection of its own. Signed-off-by: Akira Yokosawa --- Documentation/doc-guide/sphinx.rst | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/s= phinx.rst index f257c4785607..f8bbf86fa15a 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -202,7 +202,16 @@ Here are some specific guidelines for the kernel docum= entation: * Also update the content, not just the formatting, when converting documentation. =20 -* Please stick to this relative order of section title adornments: +* For inserting fixed width text blocks (for code examples, use case + examples, etc.), use ``::`` for anything that doesn't really benefit + from syntax highlighting, especially short snippets. Use + ``.. code-block:: `` for longer code blocks that benefit + from highlighting. For a short snippet of code embedded in the text, use= \`\`. + +Guidelines for title adornments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Please stick to this relative order of section title adornments: =20 1. ``=3D`` with overline for 1st level titles:: =20 @@ -225,12 +234,12 @@ Here are some specific guidelines for the kernel docu= mentation: 4th level title ~~~~~~~~~~~~~~~ =20 - Although RST doesn't mandate a specific order ("Rather than imposing a f= ixed - number and order of section title adornment styles, the order enforced w= ill be - the order as encountered."), having the higher levels the same overall m= akes - it easier to follow the documents. +Although RST doesn't mandate a specific order ("Rather than imposing a fix= ed +number and order of section title adornment styles, the order enforced wil= l be +the order as encountered."), having the higher levels the same overall mak= es +it easier to follow the documents. =20 - .. note:: +.. note:: - It is not easy to tell the levels (chapter, section, etc.) of title adornments in a particular .rst file. A title that appears first in a .rst file can be at any level of document, chapter, section, or @@ -258,7 +267,7 @@ Here are some specific guidelines for the kernel docume= ntation: .. [#rstdoc] https://docutils.sourceforge.io/docs/ref/rst/restructured= text.html#document .. [#rstdirtitle] https://docutils.sourceforge.io/docs/ref/rst/directi= ves.html#metadata-document-title =20 - .. warning:: +.. warning:: For existing documents, manually updating title adornments just to meet these guidelines is not recommended. Such changes can be error-prone = and may break section hierarchy without being caught by reviewers. They m= ay @@ -268,12 +277,6 @@ Here are some specific guidelines for the kernel docum= entation: It would be appreciated if adjustment of those adornments could be automated in some way. =20 -* For inserting fixed width text blocks (for code examples, use case - examples, etc.), use ``::`` for anything that doesn't really benefit - from syntax highlighting, especially short snippets. Use - ``.. code-block:: `` for longer code blocks that benefit - from highlighting. For a short snippet of code embedded in the text, use= \`\`. - =20 the C domain ------------ --=20 2.25.1 From nobody Wed Apr 29 09:33:15 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id A7E7BC433EF for ; Thu, 9 Jun 2022 13:28:50 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S243850AbiFIN2s (ORCPT ); Thu, 9 Jun 2022 09:28:48 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37970 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S236472AbiFIN2q (ORCPT ); Thu, 9 Jun 2022 09:28:46 -0400 Received: from mail-pl1-x62a.google.com (mail-pl1-x62a.google.com [IPv6:2607:f8b0:4864:20::62a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 77EBBC01; Thu, 9 Jun 2022 06:28:44 -0700 (PDT) Received: by mail-pl1-x62a.google.com with SMTP id d13so4586426plh.13; Thu, 09 Jun 2022 06:28:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:date:mime-version:user-agent:subject:content-language:to :cc:references:from:in-reply-to:content-transfer-encoding; bh=Mz7V2xD1G6h5TvOs7Ag8m6DrvQ9A1f2IYetUk1d+PhQ=; b=B4zn5ZGeBYoVIcQ/k+mcJqq14IHOQj3uKEcxP5ZCiIyILNtXmeX1a3/pZULGcGoyKG 9I0bdB9k4gCBE4shh70XOv3E86s8fLu3sfb0mIptRvcxAGmCsf28bCMBmAtzTLL1XylV CiMw/Vfz9t5DifHHm7LcwvGnHpoG3lnnxjvhBnH25Y2d5NagIuvrgYj8b/h2GFphW0qU 8q/kFu29nmz7X9a/m0PIVxiZFgkXpKc7cqQ31wQcsdZarUDEdq/4DCXdjTAOjUktct9J xmIlPQKtrKzknalUYLDTowIkXiVRyECcpN7gX7ZAwWUbjygMkeLhrVE/rv/XZFYEcXVX SUVQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:date:mime-version:user-agent:subject :content-language:to:cc:references:from:in-reply-to :content-transfer-encoding; bh=Mz7V2xD1G6h5TvOs7Ag8m6DrvQ9A1f2IYetUk1d+PhQ=; b=U5sBmBfKsMAN/BIjOsDGlGCHXIIloc0GMM4z2oKbXHjBiZKnV4GldADtn4uU/bpO7f GvTzyugwo89X5o+XJKIC0JFwnCQDcK+urkRwVoBzFMCUy9ZlquBzXdAGd4ilJoiGbW82 XFvV+5vVedSpo/3zvbHS7Vkxf070yAGbAmNEyPKKZivY9LJRZTvPhidcPS8VTu7merHm m19DS55K7by5QhR9CLvWETkZL1uLR7dhPCaoRWlGAh3fl42URY6Td66u5c7m2YcqWJcv fv2HTtbInMpRuP7EUCINmPalFrGBzpAyUGucEhFerozmMzVwERNURbXJ80WnJtJ87wtw hVhA== X-Gm-Message-State: AOAM5318vNVecHHdT17vl7ora9ZB7W2p2JWs9cIXiuWVtZPZIsSBZUyR zXpjuarRgIrhmLdTK90Dgxg= X-Google-Smtp-Source: ABdhPJxsVethl6NbMzTT/j6FDOIG6XvSlq+VQNCFhGOK00BjXa8MIVhSqSAUY6ozNNcfG32Nj6MKjA== X-Received: by 2002:a17:903:1211:b0:15e:8208:8cc0 with SMTP id l17-20020a170903121100b0015e82088cc0mr40322693plh.52.1654781324091; Thu, 09 Jun 2022 06:28:44 -0700 (PDT) Received: from [192.168.11.5] (KD106167171201.ppp-bb.dion.ne.jp. [106.167.171.201]) by smtp.gmail.com with ESMTPSA id l21-20020a17090b079500b001e0d4169365sm18521658pjz.17.2022.06.09.06.28.41 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 09 Jun 2022 06:28:42 -0700 (PDT) Message-ID: <15636c13-7fa2-f973-6d3d-361222b839ef@gmail.com> Date: Thu, 9 Jun 2022 22:28:40 +0900 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.9.1 Subject: [PATCH 5/5] docs/doc-guide: Put meta title for kernel-doc HTML page Content-Language: en-US To: Jonathan Corbet , linux-doc@vger.kernel.org Cc: Mauro Carvalho Chehab , "Maciej W. Rozycki" , Miguel Ojeda , linux-kernel@vger.kernel.org, Akira Yokosawa References: From: Akira Yokosawa In-Reply-To: Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" kernel-doc.rst has two 1st level section titles of "Writing kernel-doc comments" and "Including kernel-doc comments". Therefore, rather than using the first one, put a meta title of "Kernel-doc comments" for the title of the resulting HTML page by using the "title" directive. Signed-off-by: Akira Yokosawa --- Documentation/doc-guide/kernel-doc.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-gui= de/kernel-doc.rst index a7cb2afd7990..9c779bd7a751 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -1,3 +1,5 @@ +.. title:: Kernel-doc comments + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D Writing kernel-doc comments =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --=20 2.25.1