summaryrefslogtreecommitdiff
path: root/Documentation/doc-guide
diff options
context:
space:
mode:
authorJonathan Corbet <corbet@lwn.net>2022-10-19 01:29:50 +0300
committerJonathan Corbet <corbet@lwn.net>2022-10-19 01:29:50 +0300
commit554d4389166f26765cc24f0723aee2642fcc3c26 (patch)
tree8f7e46c29d04b9bf4c24d0ca0739127075e7e091 /Documentation/doc-guide
parent9abf2313adc1ca1b6180c508c25f22f9395cc780 (diff)
parent02d33e86468c604f0e2fe9a63c312dcd1a021b13 (diff)
downloadlinux-554d4389166f26765cc24f0723aee2642fcc3c26.tar.xz
Merge branch 'alabaster-rb' into docs-mw
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.
Diffstat (limited to 'Documentation/doc-guide')
-rw-r--r--Documentation/doc-guide/sphinx.rst16
1 files changed, 5 insertions, 11 deletions
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index c708cec889af..23edb427e76f 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -147,11 +147,9 @@ section of ``make help``. The generated documentation is placed in
format-specific subdirectories under ``Documentation/output``.
To generate documentation, Sphinx (``sphinx-build``) must obviously be
-installed. For prettier HTML output, the Read the Docs Sphinx theme
-(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need
-``XeLaTeX`` and ``convert(1)`` from ImageMagick
-(https://www.imagemagick.org).\ [#ink]_
-All of these are widely available and packaged in distributions.
+installed. For PDF output you'll also need ``XeLaTeX`` and ``convert(1)``
+from ImageMagick (https://www.imagemagick.org).\ [#ink]_ All of these are
+widely available and packaged in distributions.
To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
@@ -160,12 +158,8 @@ output.
It is also possible to pass an extra DOCS_CSS overlay file, in order to customize
the html layout, by using the ``DOCS_CSS`` make variable.
-By default, the build will try to use the Read the Docs sphinx theme:
-
- https://github.com/readthedocs/sphinx_rtd_theme
-
-If the theme is not available, it will fall-back to the classic one.
-
+By default, the "Alabaster" theme is used to build the HTML documentation;
+this theme is bundled with Sphinx and need not be installed separately.
The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
There is another make variable ``SPHINXDIRS``, which is useful when test