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

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: Windows password security audit tool. GUI, reports in PDF.

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

Message-ID: <dccb5233-7f4f-1be6-d1f4-bbe9f42f88e0@gmail.com>
Date:   Thu, 9 Jun 2022 22:21:44 +0900
From:   Akira Yokosawa <akiyks@...il.com>
To:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc:     Mauro Carvalho Chehab <mchehab@...nel.org>,
        "Maciej W. Rozycki" <macro@...am.me.uk>,
        Miguel Ojeda <ojeda@...nel.org>, linux-kernel@...r.kernel.org,
        Akira Yokosawa <akiyks@...il.com>
Subject: [PATCH 0/5] docs/doc-guide: Sphinx related updates

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