linux.git/Documentation/conf.py, branch v6.2-rc2

docs/sphinx: More depth in the rtd sidebar toc

2022-11-09T20:28:40+00:00

We love to nest our documenation for good structure, but that means
the table of contents needs to keep up or you can't navigate them.

Realized this trying to find the drm property documentation, which
with some shuffling around disappeared. Why I didn't realize we can do
this earlier, no idea.

Since the relevant parts of the toc are only loaded if you're in the
right .html file there's no harm in going all the way to unlimited.

Note that this has no impact on the alabaster theme (which has a much
simpler sidebar toc which doesn't show the entire hierarchy, only
what's in the local rendered file) nor on the various :toctree:
rendered inline in the output.

Signed-off-by: Daniel Vetter 
Cc: Jonathan Corbet 
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20221108115707.1232621-1-daniel.vetter@ffwll.ch
Signed-off-by: Jonathan Corbet

docs: Don't wire font sizes for HTML output

2022-11-01T21:59:40+00:00

The alabaster theme likes to provide explicit sizes for fonts, which
overrides the users's own browser settings and is guaranteed to displease
folks.  Set the font size to "inherit" so that the users browser settings
control the font size they get.  We can use the font_size configuration
option for the main body font (changing the size I'd already put there),
but the sidebar size can only be set via custom CSS.

Reported-by: Bagas Sanjaya 
Signed-off-by: Jonathan Corbet

docs: decruft Documentation/conf.py

2022-10-18T22:29:35+00:00

Remove the ancient support for the Sphinx "classic" theme; everybody will
have alabaster, so that fallback is no longer needed.

While in the neighborhood: get rid of lots of useless comment lines.  They
describe the state of Sphinx options when we first created that file and
are just clutter now.

Suggested-by: Mauro Carvalho Chehab 
Acked-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

docs: tweak some Alabaster style parameters

2022-10-13T17:14:31+00:00

This is just the beginning: tighten up the layout a bit to improve the
information density in the browser.  Also reconfigure the page width in
terms of character units (em) rather than pixels, making it more
display-independent.  To that end, add a custom.css file to
tweak Alabaster CSS settings.

Acked-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

docs: Switch the default HTML theme to alabaster

2022-10-13T17:14:12+00:00

The read-the-docs theme is not entirely attractive and doesn't give us
control over the left column.  "Alabaster" is deemed the default Sphinx
theme, it is currently maintained and shipped bundled with Sphinx itself,
so there is no need to install it separately.  Switch over to this theme as
the default for building kernel documentation; the DOCS_THEME environment
variable can still be used to select a different theme.

Acked-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

Merge branch 'docs-mw' into docs-next

2022-09-29T19:29:16+00:00

docs: reconfigure the HTML left column

2022-09-29T18:55:06+00:00

Use the html_sidebars directive to get a more useful set of links in the
left column.

Unfortunately, this is a no-op with the default RTD theme, but others
observe it.

Reviewed-by: David Vernet 
Acked-by: Jani Nikula 
Signed-off-by: Jonathan Corbet 
Acked-by: Randy Dunlap 
Link: https://lore.kernel.org/r/20220927160559.97154-4-corbet@lwn.net
Signed-off-by: Jonathan Corbet

Merge branch 'docs-mw' into docs-next

2022-09-27T19:23:18+00:00

docs/conf.py: Respect env variable SPHINX_IMGMATH

2022-09-27T19:21:43+00:00

On some distros with coarse-grained packaging policy, dvipng is
installed along with latex.  In such cases, math rendering will
use imgmath by default.  It is possible to override the choice by
specifying the option string of "-D html_math_renderer='mathjax'"
to sphinx-build (Sphinx >= 1.8).

To provide developers an easier-to-use knob, add code for an env
variable "SPHINX_IMGMATH" which overrides the automatic choice
of math renderer for html docs.

    SPHINX_IMGMATH=yes : Load imgmath even if dvipng is not found
    SPHINX_IMGMATH=no  : Don't load imgmath (fall back to mathjax)

Signed-off-by: Akira Yokosawa 
Acked-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/5a582b2b-d51c-a062-36b2-19479cf68fab@gmail.com
Signed-off-by: Jonathan Corbet

docs/conf.py: Treat mathjax as fallback math renderer

2022-09-27T19:21:43+00:00

Currently, math expressions using the "math::" directive or
the ":math:" role of Sphinx need the imgmath extension for proper
rendering in html and epub builds.
imgmath requires dvipng (and latex).
Otherwise, "make htmldocs" will complain of missing commands.

As a matter of fact, the mathjax extension is loaded by default since
Sphinx v1.8 and it is good enough for html docs without any dependency
on texlive packages.

Stop loading the imgmath extension for html docs unless requirements
for imgmath are met.

To find out whether required commands are available, add a helper
find_command(), which is a wrapper of shutil.which().

For epub docs, keep the same behavior of always loading imgmath.

Signed-off-by: Akira Yokosawa 
Acked-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/a6a877fc-dc93-2bda-a6d3-37001d99942a@gmail.com
[jc: Took out the writing of the math_renderer decision]
Signed-off-by: Jonathan Corbet