Date:   Tue, 11 Oct 2022 19:25:53 -0700
From:   Randy Dunlap <rdunlap@...radead.org>
To:     Bagas Sanjaya <bagasdotme@...il.com>,
        Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc:     linux-kernel@...r.kernel.org,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        Mauro Carvalho Chehab <mchehab@...nel.org>
Subject: Re: [PATCH v2 0/6] docs: Improvements to our HTML output



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@....net>
L:	linux-doc@...r.kernel.org
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

Powered by blists - more mailing lists