From: Jonathan Corbet <corbet@lwn.net>
To: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org,
Jani Nikula <jani.nikula@linux.intel.com>,
Mauro Carvalho Chehab <mchehab@kernel.org>,
Jonathan Corbet <corbet@lwn.net>
Subject: [PATCH RFC 0/5] docs: Improvements to our HTML output
Date: Tue, 4 Oct 2022 14:12:17 -0600 [thread overview]
Message-ID: <20221004201222.281845-1-corbet@lwn.net> (raw)
For a long time we have rejoiced that our HTML output from Sphinx is far
better than what we got from the old DocBook toolchain. But it still
leaves a lot to be desired; the following is an attempt to improve the
situation somewhat.
Sphinx has a theming mechanism for HTML rendering. Since the kernel's
adoption of Sphinx, we have been using the "Read The Docs" theme — a choice
made in a bit of a hurry to have *something* while figuring out the rest.
RTD is OK, but it is not hugely attractive, requires the installation of an
extra package, and does not observe all of the Sphinx configuration
parameters. Among other things, that makes it hard to put reasonable
contents into the left column in the HTML output.
The Alabaster theme is the default for Sphinx installations, and is bundled
with Sphinx itself. It has (IMO) nicer output and gives us the control
that we need.
So: switch to Alabaster. Additional patches adjust the documentation and
remove the RTD references from scripts/sphinx-pre-install.
The final patch changes the way that kerneldoc declarations are rendered to
(IMO) improve readability. That requires some changes to kernel-doc to
output a new container block and some CSS tweaks to improve things overall.
It should be noted that I have a long history of inflicting ugly web
designs on the net; this work is a start, but I think we could do far
better yet. It would be great if somebody who actually enjoys working with
CSS and such would help to improve what we have.
As before, I've put a copy of the rendered docs at:
https://static.lwn.net/kerneldoc/
To compare the kerneldoc changes specifically, pick a page that includes a
lot of definitions; for example:
https://static.lwn.net/kerneldoc/driver-api/media/drivers/frontends.html
vs.
https://www.kernel.org/doc/html/latest/driver-api/media/drivers/frontends.html
Jonathan Corbet (5):
docs: Switch the default HTML theme to alabaster
docs: tweak some Alabaster style parameters
docs: update sphinx.rst to reflect the default theme change
docs: sphinx-pre-install: don't require the RTD theme
docs: improve the HTML formatting of kerneldoc comments
Documentation/conf.py | 27 ++++++++++++-
Documentation/doc-guide/sphinx.rst | 16 +++-----
Documentation/sphinx-static/custom.css | 25 +++++++++++++
Documentation/sphinx/requirements.txt | 1 -
scripts/kernel-doc | 52 ++++++++++++++++----------
scripts/sphinx-pre-install | 8 ----
6 files changed, 87 insertions(+), 42 deletions(-)
create mode 100644 Documentation/sphinx-static/custom.css
--
2.37.2
next reply other threads:[~2022-10-04 20:12 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-10-04 20:12 Jonathan Corbet [this message]
2022-10-04 20:12 ` [PATCH 1/5] docs: Switch the default HTML theme to alabaster Jonathan Corbet
2022-10-05 17:22 ` Jani Nikula
2022-10-05 17:49 ` Jonathan Corbet
2022-10-06 5:09 ` Mauro Carvalho Chehab
2022-10-06 5:17 ` Mauro Carvalho Chehab
2022-10-04 20:12 ` [PATCH 2/5] docs: tweak some Alabaster style parameters Jonathan Corbet
2022-10-05 17:28 ` Jani Nikula
2022-10-05 17:46 ` Jonathan Corbet
2022-10-04 20:12 ` [PATCH 3/5] docs: update sphinx.rst to reflect the default theme change Jonathan Corbet
2022-10-04 20:12 ` [PATCH 4/5] docs: sphinx-pre-install: don't require the RTD theme Jonathan Corbet
2022-10-04 20:12 ` [PATCH 5/5] docs: improve the HTML formatting of kerneldoc comments Jonathan Corbet
2022-10-05 5:59 ` Mauro Carvalho Chehab
2022-10-05 15:29 ` Jonathan Corbet
2022-10-06 5:41 ` Mauro Carvalho Chehab
2022-10-07 16:26 ` Jonathan Corbet
2022-10-05 16:58 ` Jani Nikula
2022-10-06 5:53 ` Mauro Carvalho Chehab
2022-10-06 8:29 ` Jani Nikula
2022-10-05 5:40 ` [PATCH RFC 0/5] docs: Improvements to our HTML output Mauro Carvalho Chehab
2022-10-05 15:33 ` Jonathan Corbet
2022-10-06 5:04 ` Mauro Carvalho Chehab
2022-10-06 11:11 ` Jani Nikula
2022-10-06 13:49 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20221004201222.281845-1-corbet@lwn.net \
--to=corbet@lwn.net \
--cc=jani.nikula@linux.intel.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).