Date:   Tue, 11 Oct 2022 13:00:41 -0600
From:   Jonathan Corbet <corbet@....net>
To:     linux-doc@...r.kernel.org
Cc:     linux-kernel@...r.kernel.org,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        Jonathan Corbet <corbet@....net>
Subject: [PATCH v2 0/6] docs: Improvements to our HTML output

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

-------
Changes from the initial version:

- Tweak more alabaster style parameters, including the maximum page width.
  There will surely be disagreement over what the right value should be,
  but at least it's defined in units independent of screen resolution.

- Remove "classic" theme configuration and a bunch of other conf.py cruft.

- I've tried to answer all of the other comments, but a couple remain.  The
  sidebar contents are unchanged; making that more useful will require some
  thought and work.  The gray background on function prototypes that Jani
  pointed out is actually something I did intentionally, with the idea of
  making each declaration stand out better in the wall of text.  I still
  think it's better but am not married to it if the world disagrees.

- I've tested PDF and epub builds (no changes) and Sphinx back to v1.7.

In the absence of objections I'll be putting this into docs-next after the
merge window closes.  We can (and surely will) tweak this forever, but at
least it, I hope, shows a direction in which we can go.

Jonathan Corbet (6):
  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
  docs: decruft Documentation/conf.py

 Documentation/conf.py                  | 204 ++++---------------------
 Documentation/doc-guide/sphinx.rst     |  16 +-
 Documentation/sphinx-static/custom.css |  28 ++++
 Documentation/sphinx/requirements.txt  |   1 -
 scripts/kernel-doc                     |  52 ++++---
 scripts/sphinx-pre-install             |   8 -
 6 files changed, 91 insertions(+), 218 deletions(-)
 create mode 100644 Documentation/sphinx-static/custom.css

-- 
2.37.2

Powered by blists - more mailing lists