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

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

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

[+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