linux.git/Documentation/conf.py, branch v5.17

docs: add support for RTD dark mode

2021-12-10T21:05:55+00:00

This is actually an overlay on the top of the RTD theme, which
requires to include first the RTD theme.

It should be noticed that, when the dark theme is used, the
DOCS_CSS files won't be the last CSS themes. So, it won't
override the dark.css style by default. So, it is needed
to force the them override with "!important".

This small script, for instance, produces a nice output with
the RTD dark theme:

	DOCS_THEME=sphinx_rtd_dark_mode
	cat << EOF > dark_override.css
	  html body {
	    font-family: arial,helvetica,sans-serif;
	  }
	  html[data-theme='dark'] body {
	    color: white !important;
	  }
	  html[data-theme='dark'] .sig-name {
	    color: green !important;
	  }
	  html[data-theme='dark'] .wy-menu-vertical a {
	    color: #ffcc00 !important;
	  }
	  html[data-theme="dark"] h1, html[data-theme="dark"] h2, html[data-theme="dark"] h3 {
	    color: #ffcc00 !important;
	  }
	  html[data-theme="dark"] h4, html[data-theme="dark"] h5, html[data-theme="dark"] h6 {
	    color: #ffcc00 !important;
	  }
	  html[data-theme="dark"] h7, html[data-theme="dark"] h8, html[data-theme="dark"] h9 {
	    color: #ffcc00 !important;
	  }
	  html[data-theme="dark"] .wy-nav-content a, html[data-theme="dark"] .wy-nav-content a:visited {
	    color: #ffcc00 !important;
	  }
	EOF

	make DOCS_CSS=dark_override.css DOCS_THEME=sphinx_rtd_dark_mode htmldocs

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/90d316e055ef7f4c9021b9eada8f8d3b2e750a66.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet

docs: set format for the classic mode

2021-12-10T21:05:55+00:00

When RTD is not installed or when THEME=classic is used, the
produced docs contain some weird selections. As this theme has
several variables to customize it, set them, in order to produce
a nicer output.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/8889380606681a2b7033f73bed9717250302be2a.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet

docs: allow to pass extra DOCS_CSS themes via make

2021-12-10T21:05:55+00:00

Specially when the RTD theme is not used, it makes sense to
allow specifying extra CSS files via a make variable.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/03d09bf41ad39aa0abfe2ea3c879b09aa3a0948d.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet

docs: allow selecting a Sphinx theme

2021-12-10T21:05:55+00:00

Instead of having RTD as an almost mandatory theme, allow the
user to select other themes via DOCS_THEME environment var.

There's a catch, though: as the current theme override logic is
dependent of the RTD theme, we need to move the code which
adds the CSS overrides to be inside the RTD theme logic.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/bd20adabfd428fd3cd0e69c2cf146aa354932936.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet

docs: conf.py: fix support for Readthedocs v 1.0.0

2021-11-29T21:27:52+00:00

As described at:
	https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs

since Sphinx 1.8, the standard way to setup a custom theme is
to use html_css_files. While using html_context is OK with RTD
0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
producing a very weird html.

Tested with:
	- Sphinx 1.7.9 + sphinx-rtd-theme 0.5.2
	- Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
	- Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
	- Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0

Reported-by: Hans Verkuil 
Tested-by: Hans Verkuil 
Reviewed-by: Laurent Pinchart 
Signed-off-by: Mauro Carvalho Chehab 
Tested-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/80009f0d17ea0840d81e7e16fff6e7677919fdfc.1638004294.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Adjust \headheight for fancyhdr

2021-10-12T20:09:03+00:00

Fancyhdr prior to v4.0 outputs a message per document as follows:

    Package Fancyhdr Warning: \headheight is too small (12.0pt):
    Make it at least 13.59999pt.
    We now make it that large for the rest of the document.
    This may cause the page layout to be inconsistent, however.

Fancyhdr v4.0 complains (once a page!) as follows:

    Package fancyhdr Warning: \headheight is too small (12.0pt):
    (fancyhdr)    Make it at least 13.59999pt, for example:
    (fancyhdr)    \setlength{\headheight}{13.59999pt}.
    (fancyhdr)    You might also make \topmargin smaller to compensate:

    (fancyhdr)    \addtolength{\topmargin}{-1.59999pt}.

Related item in fancyhdr v4.0 announcement on 2021-01-04 [1]:

    Backward incompatible changes:
      - Eliminate adjustments of \headheight or \footskip, when the
        header or footer is too high.

[1]: https://www.ctan.org/ctan-ann/id/mailman.2685.1609863692.2532.ctan-ann@ctan.org

Silence the warnings by adding a couple of \addtolength commands in
the preamble.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/c5a5577e-5de8-9cd4-9253-956ccc748417@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Fix typo in CJK-language specific font settings

2021-09-06T22:53:39+00:00

There were typos in the fallback definitions of dummy LaTeX macros
for systems without CJK fonts.
They cause build errors in "make pdfdocs" on such systems.
Fix them.

Fixes: e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings")
Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/ad7615a5-f8fa-2bc3-de6b-7ed49d458964@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Teach xeCJK about character classes of quotation marks

2021-08-12T15:13:33+00:00

Quotation marks in "KR" and "JP" variants of Noto CJK fonts are half
width.
xeCJK assumes they are full width by default and does excessive kerning
around them in Korean and Japanese translations.

Give xeCJK proper hints by the \xeCJKDeclareCharClass command.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/0da9e3c5-2716-f576-1df5-2f28ea69f0e8@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Permit AutoFakeSlant for CJK fonts

2021-08-12T15:13:33+00:00

Noto CJK fonts don't provide italic shapes.
The AutoFakeSlant option of fontspec and xeCJK packages can be used as
a workaround.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/502335cc-9a95-3c2a-7744-6cc56ecaf628@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: One-half spacing for CJK translations

2021-08-12T15:13:32+00:00

CJK documents are much easier to read with a wider baseline stretch.
Applying onehalfspacing option of "setspace" package looks reasonable.

Note: \usepackage{setspace} needs to be before that of hyperref in the
preamble.
The 'extrapackages' key (available since Sphinx 2.3) is for this purpose.
For systems with Sphinx < 2.3, dummy commands of \onehalfspacing and
\singlespacing are provided instead.
One-half spacing is not effective in LaTeX sources generated by such
revisions of Sphinx.

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/547a1f1c-0bb5-20a7-ea0e-951bfc3c3925@gmail.com
Signed-off-by: Jonathan Corbet