[PATCH 0/5] docs/doc-guide: Sphinx related updates

[PATCH 0/5] docs/doc-guide: Sphinx related updates

[Akira Yokosawa]

Hi all,

This small set of patches fill in a couple of missing info and update
outdated guidelines in doc-guide/sphinx.rst.

Patch 1/5 adds a footnote on expected improvements of images embedded in
PDF documents by the support of Inkscape in kfigure.py added in v5.18.

Patch 2/5 mentions the make variable SPHINXDIRS, which is helpful in
test-building a subset of documents.  This change was inspired by
an earlier comment of Maciej.  He also suggested the update of
changes.rst to indicate the requirement of Sphinx 2.4 or later for
"make htmldocs", but changes.rst is not touched in this patch set
as there is an on-going discussion about updating minimal required
version of Sphinx [1].

[1]: "Sphinx pre v3 -- removing support"
     https://lore.kernel.org/linux-doc/LO3P123MB26810D190462B6BBBF1305F6C2A19@LO3P123MB2681.GBRP123.PROD.OUTLOOK.COM/

Patches 3/5 and 4/5 are RFCs.
The guidelines for title adornments were written well before the
transition to subdirectory based documentation.
Here, I'm suggesting a version of guidelines based on my personal
preference.  I am expecting at least a few comments from others
because I don't think there is any consensus on how far these
guidelines should be followed, especially for existing documents.
This update was inspired by private communication with Miguel and
Jon.

Patch 3/5 updates the guidelines for title adornments. The change is
done in-place for ease of review.

Patch 4/5 moves the item expanded by Patch 3/5 from the bullet lists
into its own subsection.

Patch 5/5 is a PoC of adding a meta title to kernel-doc.rst by using
the "title" directive mentioned in Patch 3/5.

Any feedback is welcome!

        Thanks, Akira
--
Akira Yokosawa (5):
  docs/doc-guide: Add footnote on Inkscape for better images in PDF
    documents
  docs/doc-guide: Mention make variable SPHINXDIRS
  docs/doc-guide: Update guidelines for title adornments
  docs/doc-guide: Pull guidelines for title adornments out into
    subsection
  docs/doc-guide: Put meta title for kernel-doc HTML page

 Documentation/doc-guide/kernel-doc.rst |  2 +
 Documentation/doc-guide/sphinx.rst     | 98 +++++++++++++++++++-------
 2 files changed, 76 insertions(+), 24 deletions(-)


base-commit: f2906aa863381afb0015a9eb7fefad885d4e5a56
-- 
2.25.1

[PATCH 1/5] docs/doc-guide: Add footnote on Inkscape for better images in PDF documents

[Akira Yokosawa]

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 <akiyks@gmail.com>
---
 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/sphinx.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/output``.
 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 need
-``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
+``XeLaTeX`` and ``convert(1)`` from ImageMagick
+(https://www.imagemagick.org).\ [#ink]_
 All of these are widely available and packaged in distributions.
 
 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.
 
 To remove the generated documentation, run ``make cleandocs``.
 
+.. [#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
 =====================
 
-- 
2.25.1

[PATCH 2/5] docs/doc-guide: Mention make variable SPHINXDIRS

[Akira Yokosawa]

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 <akiyks@gmail.com>
Cc: Maciej W. Rozycki <macro@orcam.me.uk>
---
This change is inspired from correspondence with Maciej [1].

[1]: https://lore.kernel.org/r/f4d40da6-756b-9e75-b867-cc9eedc4b232@gmail.com

--
 Documentation/doc-guide/sphinx.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.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 the classic one.
 
 The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
 
+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``.
 
 .. [#ink] Having ``inkscape(1)`` from Inkscape (https://inkscape.org)
-- 
2.25.1

[RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments

[Akira Yokosawa]

Existing guidelines predate the sub-directory wise document
management.

Update the guidelines to reflect the current state of affairs.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Miguel Ojeda <ojeda@kernel.org>
---
 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/sphinx.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 documentation:
 * Also update the content, not just the formatting, when converting
   documentation.
 
-* Please stick to this order of heading adornments:
+* Please stick to this relative order of section title adornments:
 
-  1. ``=`` with overline for document title::
+  1. ``=`` with overline for 1st level titles::
 
-       ==============
-       Document title
-       ==============
+       ===============
+       1st level title
+       ===============
 
-  2. ``=`` for chapters::
+  2. ``=`` for 2nd level titles::
 
-       Chapters
-       ========
+       2nd level title
+       ===============
 
-  3. ``-`` for sections::
+  3. ``-`` for 3rd level titles::
 
-       Section
-       -------
+       3rd level title
+       ---------------
 
-  4. ``~`` for subsections::
+  4. ``~`` for 4th level titles::
 
-       Subsection
-       ~~~~~~~~~~
+       4th level title
+       ~~~~~~~~~~~~~~~
 
   Although RST doesn't mandate a specific order ("Rather than imposing a fixed
   number and order of section title adornment styles, the order enforced will be
   the order as encountered."), having the higher levels the same overall makes
   it easier to follow the documents.
 
+  .. 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 "document
+      title".  Quote from the RST documentation\ [#rstdoc]_ with minor edit:
+
+	*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-level
+      ``index.rst`` can be considered the document title.  In HTML, as each
+      .html output has its source .rst file, the title which happens to come
+      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 .rst
+      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/restructuredtext.html#document
+    .. [#rstdirtitle] https://docutils.sourceforge.io/docs/ref/rst/directives.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 may
+    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
-- 
2.25.1

[RFC PATCH 4/5] docs/doc-guide: Pull guidelines for title adornments out into subsection

[Akira Yokosawa]

As it becomes too large as an item in bullet lists, make it a
subsection of its own.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 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/sphinx.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 documentation:
 * Also update the content, not just the formatting, when converting
   documentation.
 
-* 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:: <language>`` 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:
 
   1. ``=`` with overline for 1st level titles::
 
@@ -225,12 +234,12 @@ Here are some specific guidelines for the kernel documentation:
        4th level title
        ~~~~~~~~~~~~~~~
 
-  Although RST doesn't mandate a specific order ("Rather than imposing a fixed
-  number and order of section title adornment styles, the order enforced will be
-  the order as encountered."), having the higher levels the same overall makes
-  it easier to follow the documents.
+Although RST doesn't mandate a specific order ("Rather than imposing a fixed
+number and order of section title adornment styles, the order enforced will be
+the order as encountered."), having the higher levels the same overall makes
+it easier to follow the documents.
 
-  .. 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 documentation:
     .. [#rstdoc] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document
     .. [#rstdirtitle] https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title
 
-  .. 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 may
@@ -268,12 +277,6 @@ Here are some specific guidelines for the kernel documentation:
     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
-  ``.. code-block:: <language>`` for longer code blocks that benefit
-  from highlighting. For a short snippet of code embedded in the text, use \`\`.
-
 
 the C domain
 ------------
-- 
2.25.1

[PATCH 5/5] docs/doc-guide: Put meta title for kernel-doc HTML page

[Akira Yokosawa]

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 <akiyks@gmail.com>
---
 Documentation/doc-guide/kernel-doc.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/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
+
 ===========================
 Writing kernel-doc comments
 ===========================
-- 
2.25.1

Re: [PATCH 2/5] docs/doc-guide: Mention make variable SPHINXDIRS

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> 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 <akiyks@gmail.com>
> Cc: Maciej W. Rozycki <macro@orcam.me.uk>
> ---
> This change is inspired from correspondence with Maciej [1].
>
> [1]: https://lore.kernel.org/r/f4d40da6-756b-9e75-b867-cc9eedc4b232@gmail.com
>
> --
>  Documentation/doc-guide/sphinx.rst | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.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 the classic one.
>  
>  The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
>  
> +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.

This should definitely be documented, it's kind of sad that we never did
that.  Rather than redirect readers to type a "make" command, though,
why not just tell them how to use it here?

Thanks,

jon

Re: [PATCH 2/5] docs/doc-guide: Mention make variable SPHINXDIRS

[Akira Yokosawa]

On Thu, 09 Jun 2022 09:26:17 -0600,
Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
[...]
>> --- 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 the classic one.
>>  
>>  The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
>>  
>> +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.
> 
> This should definitely be documented, it's kind of sad that we never did
> that.  Rather than redirect readers to type a "make" command, though,
> why not just tell them how to use it here?

Good point.
I have updated the hunk as follows:

+There is another make variable ``SPHINXDIRS``, which is useful when test
+building a subset of documentation.  For example, you can build documents
+under ``Documentation/doc-guide`` by running
+``make SPHINXDIRS=doc-guide htmldocs``.
+The documentation section of ``make help`` will show you the list of
+subdirectories you can specify.

Thoughts?

        Thanks, Akira

> 
> Thanks,
> 
> jon

Re: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments

[Jani Nikula]

On Thu, 09 Jun 2022, Akira Yokosawa <akiyks@gmail.com> wrote:
> Existing guidelines predate the sub-directory wise document
> management.
>
> Update the guidelines to reflect the current state of affairs.
>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Cc: Miguel Ojeda <ojeda@kernel.org>
> ---
>  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/sphinx.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 documentation:
>  * Also update the content, not just the formatting, when converting
>    documentation.
>  
> -* Please stick to this order of heading adornments:
> +* Please stick to this relative order of section title adornments:
>  
> -  1. ``=`` with overline for document title::
> +  1. ``=`` with overline for 1st level titles::
>  
> -       ==============
> -       Document title
> -       ==============
> +       ===============
> +       1st level title
> +       ===============
>  
> -  2. ``=`` for chapters::
> +  2. ``=`` for 2nd level titles::
>  
> -       Chapters
> -       ========
> +       2nd level title
> +       ===============
>  
> -  3. ``-`` for sections::
> +  3. ``-`` for 3rd level titles::
>  
> -       Section
> -       -------
> +       3rd level title
> +       ---------------
>  
> -  4. ``~`` for subsections::
> +  4. ``~`` for 4th level titles::
>  
> -       Subsection
> -       ~~~~~~~~~~
> +       4th level title
> +       ~~~~~~~~~~~~~~~
>  
>    Although RST doesn't mandate a specific order ("Rather than imposing a fixed
>    number and order of section title adornment styles, the order enforced will be
>    the order as encountered."), having the higher levels the same overall makes
>    it easier to follow the documents.
>  
> +  .. 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 "document
> +      title".  Quote from the RST documentation\ [#rstdoc]_ with minor edit:
> +
> +	*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-level
> +      ``index.rst`` can be considered the document title.  In HTML, as each
> +      .html output has its source .rst file, the title which happens to come
> +      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 .rst
> +      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/restructuredtext.html#document
> +    .. [#rstdirtitle] https://docutils.sourceforge.io/docs/ref/rst/directives.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 may
> +    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.
> +

When I wrote the original guidelines, it was my subjective decision to
steer towards using the same title adornment styles and ordering across
the kernel documentation. I intentionally left out all the
reStructuredText details about this, because the definitive
documentation is the reStructuredText documentation we can refer to.

While the "Nth level title" is a more precise description, I'm not sure
it's actually helpful without describing how these levels should map to
kernel documentation structure. (Not saying the original did that
either, but then there wasn't much structure to speak of.)

Improving the documentation on documentation is great, but I think it's
a bad sign when length of the notes and warnings on something far exceed
the length of the thing being documented. The bulk of the text should be
helpful enough for people to DTRT, while leaving out exhaustive
descriptions of all the details that should just be references to
reStructuredText documentation.


BR,
Jani.




>  * 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

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments

[Miguel Ojeda]

On Fri, Jun 10, 2022 at 11:11 AM Jani Nikula
<jani.nikula@linux.intel.com> wrote:
>
> When I wrote the original guidelines, it was my subjective decision to
> steer towards using the same title adornment styles and ordering across
> the kernel documentation. I intentionally left out all the
> reStructuredText details about this, because the definitive
> documentation is the reStructuredText documentation we can refer to.
>
> While the "Nth level title" is a more precise description, I'm not sure
> it's actually helpful without describing how these levels should map to
> kernel documentation structure. (Not saying the original did that
> either, but then there wasn't much structure to speak of.)

To give a bit of context: this patch followed from a question I asked
to Jonathan and Akira privately. Currently it is hard to tell the
"nesting level", and even worse, existing files are not consistent and
checking is not automated. Therefore, an easy way to handle this is to
request to follow the same pattern regardless of nesting across the
tree.

> Improving the documentation on documentation is great, but I think it's
> a bad sign when length of the notes and warnings on something far exceed
> the length of the thing being documented. The bulk of the text should be
> helpful enough for people to DTRT, while leaving out exhaustive
> descriptions of all the details that should just be references to
> reStructuredText documentation.

Perhaps we can move the rationale to the commit message, and keep only
the current rules in the document. What about something like:

"""
Please stick to this relative order of adornments within each file
(i.e. regardless of nesting level across the kernel tree):

    1. ``=`` with overline.
    2. ``=``.
    3. ``-``.
    4. ``~``.

For instance::

    =====
    First
    =====

    Second
    ======

    Third
    -----

    Fourth
    ~~~~~~
"""

Cheers,
Miguel

Re: [PATCH 0/5] docs/doc-guide: Sphinx related updates

[Miguel Ojeda]

On Thu, Jun 9, 2022 at 3:21 PM Akira Yokosawa <akiyks@gmail.com> wrote:
>
> This update was inspired by private communication with Miguel and
> Jon.

Thanks for working on the update, Akira!

Cheers,
Miguel

Re: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments

[Akira Yokosawa]

On Fri, 10 Jun 2022 18:08:43 +0200,
Miguel Ojeda wrote:
> On Fri, Jun 10, 2022 at 11:11 AM Jani Nikula
> <jani.nikula@linux.intel.com> wrote:
Thank Jani and Miguel for chiming in!
As this is a RFC patch, I'm glad to have nice comments from both of you.

>>
>> When I wrote the original guidelines, it was my subjective decision to
>> steer towards using the same title adornment styles and ordering across
>> the kernel documentation. I intentionally left out all the
>> reStructuredText details about this, because the definitive
>> documentation is the reStructuredText documentation we can refer to.
>>
>> While the "Nth level title" is a more precise description, I'm not sure
>> it's actually helpful without describing how these levels should map to
>> kernel documentation structure. (Not saying the original did that
>> either, but then there wasn't much structure to speak of.)
I agree that we need to cover in doc-guide the way the kernel documentation
is organized and managed.  Total lack of such documentation is kind of
surprising to me.

> 
> To give a bit of context: this patch followed from a question I asked
> to Jonathan and Akira privately. Currently it is hard to tell the
> "nesting level", and even worse, existing files are not consistent and
> checking is not automated. Therefore, an easy way to handle this is to
> request to follow the same pattern regardless of nesting across the
> tree.
> 
>> Improving the documentation on documentation is great, but I think it's
>> a bad sign when length of the notes and warnings on something far exceed
>> the length of the thing being documented. The bulk of the text should be
>> helpful enough for people to DTRT, while leaving out exhaustive
>> descriptions of all the details that should just be references to
>> reStructuredText documentation.

So, I was not aware of such a hidden rule on what should _not_ be in
doc-guide.  :-)
In my opinion, RST documentation is not easy to follow especially for
new contributors, and putting some useful tips somewhere in doc-guide
would improve situation.

I agree with you that those notes and warning don't belong to guidelines.

Maybe add a section collecting RST tips and tricks mainly consisting
of pointers to RST and docutils documentation.

> 
> Perhaps we can move the rationale to the commit message, and keep only
> the current rules in the document. What about something like:
> 
> """
> Please stick to this relative order of adornments within each file
> (i.e. regardless of nesting level across the kernel tree):
> 
>     1. ``=`` with overline.
>     2. ``=``.
>     3. ``-``.
>     4. ``~``.
> 
> For instance::
> 
>     =====
>     First
>     =====
> 
>     Second
>     ======
> 
>     Third
>     -----
> 
>     Fourth
>     ~~~~~~
> """

I'm more inclined to keep "level"s in the example.
Without them, a new contributor might be confused to use those
adornments exactly in that order, for example:

    ==============
    Document title
    ==============

    Chapter A
    =========

    Section A.1
    -----------

    Section A.2
    ~~~~~~~~~~~

    Section A.3
    ???????????

Unlikely, but possible...

Anyway, I'll post a v2 for your further comments.
Might take a while.

        Thanks, Akira
> 
> Cheers,
> Miguel

Re: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments

[Mauro Carvalho Chehab]

Em Sat, 11 Jun 2022 12:15:54 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> On Fri, 10 Jun 2022 18:08:43 +0200,
> Miguel Ojeda wrote:
> > On Fri, Jun 10, 2022 at 11:11 AM Jani Nikula
> > <jani.nikula@linux.intel.com> wrote:  
> Thank Jani and Miguel for chiming in!
> As this is a RFC patch, I'm glad to have nice comments from both of you.
> 
> >>
> >> When I wrote the original guidelines, it was my subjective decision to
> >> steer towards using the same title adornment styles and ordering across
> >> the kernel documentation. I intentionally left out all the
> >> reStructuredText details about this, because the definitive
> >> documentation is the reStructuredText documentation we can refer to.
> >>
> >> While the "Nth level title" is a more precise description, I'm not sure
> >> it's actually helpful without describing how these levels should map to
> >> kernel documentation structure. (Not saying the original did that
> >> either, but then there wasn't much structure to speak of.)  
> I agree that we need to cover in doc-guide the way the kernel documentation
> is organized and managed.  Total lack of such documentation is kind of
> surprising to me.
> 
> > 
> > To give a bit of context: this patch followed from a question I asked
> > to Jonathan and Akira privately. Currently it is hard to tell the
> > "nesting level", and even worse, existing files are not consistent and
> > checking is not automated. Therefore, an easy way to handle this is to
> > request to follow the same pattern regardless of nesting across the
> > tree.

The thing is that there were *lots* of Kernel documents that were already
following ReST syntax, some requiring minor adjustments.

Yet, each one used its own way to indent the several levels. On most
of those, the indentation was:

	First
	=====

	Second
	------

Having to rewrite all tags at the entire document with no real gain,
while having a batch of thousands of documents left to be converted
from .txt to .rst was simply a waste of resources. At the documents
I converted myself, I just kept whatever level indentation it was
already there.

Going further, even now I would really prefer not needing to review
patches that are just changing the tags for each indentation level.
Again, this would be a waste of resources. I would very much like
to receive more patches adding kernel-doc documentation and ReST
changes to document the Kernel core APIs.

Now, for *new* documents, I agree that it makes sense to use a
standard way, at least up to level 3, like:

	=====
	First
	=====

	Second
	======

	Third
	-----

Which is quite intuitive to me. 

> >   
> >> Improving the documentation on documentation is great, but I think it's
> >> a bad sign when length of the notes and warnings on something far exceed
> >> the length of the thing being documented. The bulk of the text should be
> >> helpful enough for people to DTRT, while leaving out exhaustive
> >> descriptions of all the details that should just be references to
> >> reStructuredText documentation.  
> 
> So, I was not aware of such a hidden rule on what should _not_ be in
> doc-guide.  :-)
> In my opinion, RST documentation is not easy to follow especially for
> new contributors, and putting some useful tips somewhere in doc-guide
> would improve situation.
> 
> I agree with you that those notes and warning don't belong to guidelines.
> 
> Maybe add a section collecting RST tips and tricks mainly consisting
> of pointers to RST and docutils documentation.
> 
> > 
> > Perhaps we can move the rationale to the commit message, and keep only
> > the current rules in the document. What about something like:
> > 
> > """
> > Please stick to this relative order of adornments within each file
> > (i.e. regardless of nesting level across the kernel tree):
> > 
> >     1. ``=`` with overline.
> >     2. ``=``.
> >     3. ``-``.
> >     4. ``~``.

At least at the charset I use here, `~` is bigger than `-`. For me, it sounds
counter-intuitive to use it there... Personally, i prefer `^` for the
4th level.

Yet, the forth level (and the following ones) generally happen when someone
needs to add something to an already-existing document. I doubt anyone that
already works with ReST would ever look at the doc-guide if they need to 
add a 4th/5th/... level on an already existing documents.

So, IMO, it is pointless to define or expect that all docs would use the
same level markup after the third level.


> > For instance::
> > 
> >     =====
> >     First
> >     =====
> > 
> >     Second
> >     ======
> > 
> >     Third
> >     -----
> > 
> >     Fourth
> >     ~~~~~~
> > """  
> 
> I'm more inclined to keep "level"s in the example.

Agreed.

Regards,
Mauro

Re: [PATCH 0/5] docs/doc-guide: Sphinx related updates

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> Hi all,
>
> This small set of patches fill in a couple of missing info and update
> outdated guidelines in doc-guide/sphinx.rst.

I've applied patches 1 and 5; I'm not quite sure where we stand with the
others...

Thanks,

jon

Re: [PATCH 0/5] docs/doc-guide: Sphinx related updates

[Akira Yokosawa]

[+CC: Jani]
Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>> Hi all,
>>
>> This small set of patches fill in a couple of missing info and update
>> outdated guidelines in doc-guide/sphinx.rst.
> 
> I've applied patches 1 and 5; I'm not quite sure where we stand with the
> others...

Yeah, I've got lost after seeing all those different views on RFC 3/5.

I'll post v2 of 2/5 as a single patch soon.

        Thanks, Akira

> 
> Thanks,
> 
> jon