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
Existing guidelines predate the sub-directory wise document
management.
Update the guidelines to reflect the current state of affairs.
Signed-off-by: Akira Yokosawa <[email protected]>
Cc: Miguel Ojeda <[email protected]>
---
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
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 <[email protected]>
Cc: Maciej W. Rozycki <[email protected]>
---
This change is inspired from correspondence with Maciej [1].
[1]: https://lore.kernel.org/r/[email protected]
--
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
Akira Yokosawa <[email protected]> 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 <[email protected]>
> Cc: Maciej W. Rozycki <[email protected]>
> ---
> This change is inspired from correspondence with Maciej [1].
>
> [1]: https://lore.kernel.org/r/[email protected]
>
> --
> 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
On Thu, 09 Jun 2022 09:26:17 -0600,
Jonathan Corbet wrote:
> Akira Yokosawa <[email protected]> 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
On Thu, 09 Jun 2022, Akira Yokosawa <[email protected]> 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 <[email protected]>
> Cc: Miguel Ojeda <[email protected]>
> ---
> 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
On Fri, Jun 10, 2022 at 11:11 AM Jani Nikula
<[email protected]> 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
On Thu, Jun 9, 2022 at 3:21 PM Akira Yokosawa <[email protected]> wrote:
>
> This update was inspired by private communication with Miguel and
> Jon.
Thanks for working on the update, Akira!
Cheers,
Miguel
On Fri, 10 Jun 2022 18:08:43 +0200,
Miguel Ojeda wrote:
> On Fri, Jun 10, 2022 at 11:11 AM Jani Nikula
> <[email protected]> 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
Em Sat, 11 Jun 2022 12:15:54 +0900
Akira Yokosawa <[email protected]> escreveu:
> On Fri, 10 Jun 2022 18:08:43 +0200,
> Miguel Ojeda wrote:
> > On Fri, Jun 10, 2022 at 11:11 AM Jani Nikula
> > <[email protected]> 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
Akira Yokosawa <[email protected]> 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
[+CC: Jani]
Jonathan Corbet wrote:
> Akira Yokosawa <[email protected]> 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