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

On Tue, 04 Oct 2022, Jonathan Corbet <corbet@lwn.net> 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 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.

I admit my wish-list replies to this thread may seem a bit obnoxious,
when I'm not prepared to contribute. Sorry about that. My intention was
not to block any of this, rather muse about what the future direction
might be.

Overall I think this is an improvement.

There's only two things that I'd like to get addressed, not necessarily
now, but eventually:

- As mentioned, the main div width as pixels in the alabaster
  theme. It's really crappy on wide 4K displays. Only a quarter of the
  full screen width is used.

- The function/struct/etc. main descriptions are now displayed in the
  gray background, along with the "declaration", instead of white
  background. Is that an intenational alabaster feature, or is it
  something we do to cause that? Seems like the description gets a bit
  hidden there.


BR,
Jani.


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

-- 
Jani Nikula, Intel Open Source Graphics Center

Jani Nikula <jani.nikula@linux.intel.com> writes:

> I admit my wish-list replies to this thread may seem a bit obnoxious,
> when I'm not prepared to contribute. Sorry about that. My intention was
> not to block any of this, rather muse about what the future direction
> might be.

Wish lists are good.  As noted before, if we're depending on me to come
up with the web design, we're in trouble...

> Overall I think this is an improvement.
>
> There's only two things that I'd like to get addressed, not necessarily
> now, but eventually:
>
> - As mentioned, the main div width as pixels in the alabaster
>   theme. It's really crappy on wide 4K displays. Only a quarter of the
>   full screen width is used.
>
> - The function/struct/etc. main descriptions are now displayed in the
>   gray background, along with the "declaration", instead of white
>   background. Is that an intenational alabaster feature, or is it
>   something we do to cause that? Seems like the description gets a bit
>   hidden there.

Both of these should be relatively easily done with CSS overrides, I'll
look into it.

jon

Hi Jon,

Em Tue,  4 Oct 2022 14:12:17 -0600
Jonathan Corbet <corbet@lwn.net> 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

Mauro Carvalho Chehab <mchehab@kernel.org> writes:

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

Definitely worth doing; I'm not sure how much flexibility there is
there.

I'd *really* like to avoid carrying our own theme if at all possible...

The right solution might be to actually split the books apart and do the
intersphinx thing; I've not really looked into that at all.

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

Yeah, Alabaster doesn't seem to have that.  Providing that ability in
conf.py shouldn't be *that* hard to do; it doesn't use that many colors,
though there might be a fair amount of CSS to override.

Thanks,

jon

Em Wed, 05 Oct 2022 09:33:16 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab@kernel.org> writes:
> 
> > I would play with the sidebar options used by Alabaster in order to
> > try to make the TOC more useful.  
> 
> Definitely worth doing; I'm not sure how much flexibility there is
> there.
>
> I'd *really* like to avoid carrying our own theme if at all possible...

Yeah, agreed. 

Btw right now if you don't have RTD installed, it will already fallback to 
classic Sphinx-native theme, on a non-optimized way, as it will be using the
CSS wrote for RTD.


> The right solution might be to actually split the books apart and do the
> intersphinx thing; I've not really looked into that at all.

Yeah, we've been postponing using intersphinx for quite a while. Perhaps
we could start supporting it. One expected advantage would be to make
life easier when building just a single book, as intersphinx should keep
the cross-references working and it should not produce extra warnings due 
to references that belong to other books.

> > 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.  
> 
> Yeah, Alabaster doesn't seem to have that.  Providing that ability in
> conf.py shouldn't be *that* hard to do; it doesn't use that many colors,
> though there might be a fair amount of CSS to override.

RTD dark mode [1] solves it in runtime using a CSS with:

	html[data-theme='dark'] body {
	  color: #bfbfbf;
	}

A JS sets "data-theme" to dark in order to activate it in runtime[1] with:

	    document.documentElement.setAttribute('data-theme', 'dark');

It also comes with a .py file that selects the default.

But yeah, there are a fair amount of CSS to override.

Also, I suspect that maintaining it can be a challenge. Not sure if it
worth the efforts.

[1] https://github.com/MrDogeBro/sphinx_rtd_dark_mode/tree/main/sphinx_rtd_dark_mode

Regards,
Mauro