Re: [PATCH RFC 0/5] docs: Improvements to our HTML output

[Mauro Carvalho Chehab]

Hi Jon,

Em Tue,  4 Oct 2022 14:12:17 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:

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

Nice to see it defaulting to one of the bundled themes! Not needing to
install a theme by default is a nice addition.

> 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

There's one change there that I didn't like much: at the original page,
the index shows the full index, allowing to see exactly on what part of the
index the page is sitting, e. g:

...
 The Linux driver implementer's API guide
   Media subsystem kernel internal API
     1. Media Subsystem Profile
     2. Video4Linux devices
     3. Digital TV (DVB) devices
     4. Remote Controller devices
     5. Media Controller devices
     6. CEC Kernel Support
     7. Pixel data transmitter and receiver drivers
     8. Writing camera sensor drivers
            9. Media driver-specific documentation
                9.1. Video4Linux (V4L) drivers
                9.2. Digital TV drivers


While, after the change, it shows only:

  Table of Contents
    9.2.2. Frontend drivers
        9.2.2.1. Frontend attach headers

IMO, the RTD's index output is a lot more useful, as someone reading this
would very likely need/want to navigate to other chapters of the same
part of the documentation, allowing to quickly navigate outside the 
item 9.2.2.

On the other hand, hiding the books outside the kAPI guide makes sense.

I would play with the sidebar options used by Alabaster in order to
try to make the TOC more useful.

-

On a side note, one thing I miss on all default themes is a way to dynamically
use dark mode. That's btw why I ended adding non-default support for 
'sphinx_rtd_dark_mode' (which also requires an external package). At the time
I added CSS/themes customization support to the build system, this was the only 
theme that allowed to switch to either dark/light mode. It would be really cool 
if Alabaster (or some other default themes) could honor the user's preference
between light/dark modes.

Regards,
Mauro