On 10/12/22 02:00, Jonathan Corbet wrote: > 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. > Hmm, I can't cleanly apply this patch series on top of either Linus's tree or linux-next due to conflicts on [1/6]. On what commit this series is based on? -- An old man doll... just what I always wanted! - Clara
