On 10/11/22 19:10, Bagas Sanjaya wrote: > 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? Normally Jon uses this (from the MAINTAINERS file): DOCUMENTATION M: Jonathan Corbet <corbet@xxxxxxx> L: linux-doc@xxxxxxxxxxxxxxx S: Maintained P: Documentation/doc-guide/maintainer-profile.rst T: git git://git.lwn.net/linux.git docs-next Did you try that one? -- ~Randy
