Documentation/conf.py | 204 ++++--------------------- Documentation/doc-guide/sphinx.rst | 16 +- Documentation/sphinx-static/custom.css | 28 ++++ Documentation/sphinx/requirements.txt | 1 - scripts/kernel-doc | 52 ++++--- scripts/sphinx-pre-install | 8 - 6 files changed, 91 insertions(+), 218 deletions(-) create mode 100644 Documentation/sphinx-static/custom.css
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. Jonathan Corbet (6): 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 docs: decruft Documentation/conf.py Documentation/conf.py | 204 ++++--------------------- Documentation/doc-guide/sphinx.rst | 16 +- Documentation/sphinx-static/custom.css | 28 ++++ Documentation/sphinx/requirements.txt | 1 - scripts/kernel-doc | 52 ++++--- scripts/sphinx-pre-install | 8 - 6 files changed, 91 insertions(+), 218 deletions(-) create mode 100644 Documentation/sphinx-static/custom.css -- 2.37.2
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
Bagas Sanjaya <bagasdotme@gmail.com> writes: > 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? docs-next, which is still running off the pre-6.0 base until after the merge window closes. If I need to post another round before merging I'll drag everything forward to a more current base. Thanks, jon
Hi Jon,
On Wed, 12 Oct 2022 06:38:51 -0600, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>
>> 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?
>
> docs-next, which is still running off the pre-6.0 base until after the
> merge window closes.
Hmm...
Actually, I can't apply 1/6 cleanly on docs-next, either.
As I have your tree in my local repo, "git am -3" worked and pointed
out there is a merge conflict.
It turns out that one of the hunks in 1/6 doesn't match what could be
applied cleanly.
[From 1/6]:
------------------------------------------------------
@@ -371,7 +393,7 @@ html_use_smartypants = False
# Custom sidebar templates, maps document names to template names.
# Note that the RTD theme ignores this
-html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
+html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']}
# Additional templates that should be rendered to pages, maps page names to
# template names.
------------------------------------------------------
What can be cleanly applied:
------------------------------------------------------
@@ -371,7 +393,7 @@ html_use_smartypants = False
# Custom sidebar templates, maps document names to template names.
# Note that the RTD theme ignores this.
-html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
+html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']}
# Additional templates that should be rendered to pages, maps page names to
# template names.
------------------------------------------------------
There is an additional period at the comment of:
> # Note that the RTD theme ignores this.
^
So if you remove the period first, you should be able to apply the
patch set cleanly starting from docs-next or linux-next, I guess.
Sidenote: I see this warning when applying 5/6:
.git/rebase-apply/patch:18: trailing whitespace.
margin: 20px 10px 0 10px;
warning: 1 line adds whitespace errors.
Hope this helps.
Akira
>
> If I need to post another round before merging I'll drag everything
> forward to a more current base.
>
> Thanks,
>
> jon
Akira Yokosawa <akiyks@gmail.com> writes: > Actually, I can't apply 1/6 cleanly on docs-next, either. > As I have your tree in my local repo, "git am -3" worked and pointed > out there is a merge conflict. > > It turns out that one of the hunks in 1/6 doesn't match what could be > applied cleanly. OK, apologies...the branch that stuff is on was split out some time ago, and I had to perform surgery on docs-next in the meantime. I should have rebased it. I've done so now and will send a v3 to the list; I'll try to avoid copying everybody again because there are no other changes. Thanks, jon
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@lwn.net> L: linux-doc@vger.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
On 10/12/22 09:25, Randy Dunlap wrote: >> 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@lwn.net> > L: linux-doc@vger.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? > Hi Randy, I can't fetch that repo (possibly blocked by my ISP), so I have to apply against linux-next instead. -- An old man doll... just what I always wanted! - Clara
Em Tue, 11 Oct 2022 13:00:41 -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. > > 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. No objections from my side. Surely more things could be tweaked. In particular, I didn't like having two ToCs at the index (a complete one and a second one pointing to where we are at the docs), but that's a lot better than before, so, I'm OK with that. Feel free to add my ack to the patches: Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Regards, Mauro > > Jonathan Corbet (6): > 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 > docs: decruft Documentation/conf.py > > Documentation/conf.py | 204 ++++--------------------- > Documentation/doc-guide/sphinx.rst | 16 +- > Documentation/sphinx-static/custom.css | 28 ++++ > Documentation/sphinx/requirements.txt | 1 - > scripts/kernel-doc | 52 ++++--- > scripts/sphinx-pre-install | 8 - > 6 files changed, 91 insertions(+), 218 deletions(-) > create mode 100644 Documentation/sphinx-static/custom.css >
Mauro Carvalho Chehab <mchehab@kernel.org> writes: > No objections from my side. Surely more things could be tweaked. In > particular, I didn't like having two ToCs at the index (a complete one > and a second one pointing to where we are at the docs), but that's a lot > better than before, so, I'm OK with that. Oops...that was actually a leftover from my initial attempts to improve the information there. That's not what the patches create...I've updated the rendered docs to reflect the actual output. Sorry for the confusion, jon
© 2016 - 2026 Red Hat, Inc.