linux.git/Documentation/conf.py, branch v6.0

docs/conf.py: add function attribute '__fix_address' to conf.py

2022-08-26T22:47:13+00:00

Stephen Rothwell reported htmldocs warning when merging net-next:

Documentation/networking/kapi:26: net/core/skbuff.c:780: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 19]
  void __fix_address kfree_skb_reason (struct sk_buff *skb, enum skb_drop_reason reason)
  -------------------^

Add __fix_address keyword to c_id_attributes array in conf.py to fix
the warning.

Link: https://lore.kernel.org/linux-next/20220825154105.534d78ab@canb.auug.org.au/
Reported-by: Stephen Rothwell 
Signed-off-by: Menglong Dong 
Tested-by: Bagas Sanjaya 
Signed-off-by: Jonathan Corbet

docs/conf.py: Cope with removal of language=None in Sphinx 5.0.0

2022-06-01T15:26:05+00:00

One of the changes in Sphinx 5.0.0 [1] says [sic]:

    5.0.0 final

     - #10474: language does not accept None as it value.
       The default value of language becomes to 'en' now.

[1]: https://www.sphinx-doc.org/en/master/changes.html#release-5-0-0-released-may-30-2022

It results in a new warning from Sphinx 5.0.0 [sic]:

    WARNING: Invalid configuration value found: 'language = None'.
    Update your configuration to a valid langauge code. Falling
    back to 'en' (English).

Silence the warning by using 'en'.
It works with all the Sphinx versions required for building
kernel documentation (1.7.9 or later).

Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/bd0c2ddc-2401-03cb-4526-79ca664e1cbe@gmail.com
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Pull LaTeX preamble part out of conf.py

2022-02-24T19:26:13+00:00

Quote from Jon's remark [1]:

    I do notice that Documentation/conf.py is getting large and
    unapproachable.  At some future point, it might be nice to pull
    all of the latex stuff out into a separate file where it won't
    scare people who stumble into it by accident.

Pull LaTeX preamble settings added since commit 3b4c963243b1 ("docs:
conf.py: adjust the LaTeX document output") out into
sphinx/kerneldoc-preamble.sty.

It will be copied to the build directory by the added
"latex_additional_files" setting in conf.py.

As a bonus, LaTeX/TeX code can be maintained without escaping backslashes.

To compensate the loss of change history in sphinx/kerneldoc-preamble.sty,
here is a list of changes made in conf.py:

  - f7ebe6b76940 ("docs: Activate exCJK only in CJK chapters")
  - 0afd4df0d16a ("docs: pdfdocs: Prevent column squeezing by tabulary")
  - 659653c9e546 ("docs: pdfdocs: Refactor config for CJK document")
  - e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings")
  - 7eb368cc319b ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible")
  - 35382965bdd2 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations")
  - 77abc2c230b1 ("docs: pdfdocs: One-half spacing for CJK translations")
  - 788d28a25799 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts")
  - 29ac9822358f ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks")
  - 7c5c18bdb656 ("docs: pdfdocs: Fix typo in CJK-language specific font settings")
  - aa872e0647dc ("docs: pdfdocs: Adjust \headheight for fancyhdr")
  - 8716ef413aa5 ("docs: pdfdocs: Tweak width params of TOC")
  - 66939df53948 ("docs: pdfdocs: Switch default CJK font to KR variants")
  - 7b686a2ea1e4 ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles")
  - 5d9158e3c762 ("docs/translations: Skip CJK contents if suitable fonts not found")
  - b774cc46313b ("docs: pdfdocs: Move CJK monospace font setting to main conf.py")

[1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/

Suggested-by: Jonathan Corbet 
Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Move CJK monospace font setting to main conf.py

2022-02-15T23:35:54+00:00

As LaTeX macros for CJK font settings can have Latin-script font
settings as well, settings under Documentation/translations/ can
be moved to the main conf.py.

By this change, translations.pdf built by top-level "make pdfdocs"
can have properly aligned ascii-art diagrams except for Korean
ones.

For the reason of remaining misalignment in Korean diagrams, see
changelog of commit a90dad8f610a ("docs: pdfdocs: Add conf.py
local to translations for ascii-art alignment").

Signed-off-by: Akira Yokosawa 
Cc: Jonathan Corbet 
Link: https://lore.kernel.org/r/eb87790a-03f4-9f29-c8a3-ef2c3e78ca18@gmail.com
Signed-off-by: Jonathan Corbet

docs/translations: Skip CJK contents if suitable fonts not found

2022-02-15T23:35:54+00:00

On systems without "Noto Sans CJK" fonts, CJK chapters in
translations.pdf are full of "TOFU" boxes, with a long build time and
a large log file containing lots of missing-font warnings.

Avoid such waste of time and resources by skipping CJK chapters when
CJK fonts are not available.

To skip whole chapters, change the definition of
\kerneldocBegin{SC|TC|KR|JP} commands so that they can have an argument
to be ignored.
This works as far as the argument (#1) is not used in the command.
In place of skipped contents, put a note on skipped contents at the
beginning of the PDF.

Change the call sites in index.rst of CJK translations accordingly.

When CJK fonts are available, existing command definitions with
no argument just work.  LaTeX engine will see additional pairs of
"{" and "}", which add a level of grouping without having any effect
on typesetting.

Signed-off-by: Akira Yokosawa 
Cc: Jonathan Corbet 
Link: https://lore.kernel.org/r/3359ca41-b81d-b2c7-e437-7618efbe241d@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Enable CJKspace in TOC for Korean titles

2022-02-15T23:35:53+00:00

Korean (Hangul) titles in Table of Contents of translations.pdf
don't have inter-phrase spaces.

This is because the CJKspace option of xeCJK is disabled by
default.

Restore the spaces by enabling the option at the beginning of every
document and disable it in the \kerneldocBegin{SC|TC|JP} commands.

Signed-off-by: Akira Yokosawa 
Cc: Jonathan Corbet 
Link: https://lore.kernel.org/r/19141b3e-01d9-1f6d-5020-42fbda784831@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Switch default CJK font to KR variants

2022-02-15T23:35:53+00:00

xeCJK is enabled in Table of Contents (TOC) so that translations.pdf
built by top-level "make pdfdocs" can have its TOC typeset properly.

This causes quotation marks and apostrophe symbols appear too wide in
Latin-script docs.
This is because (1) Sphinx converts ASCII symbols into multi-byte
UTF-8 ones in LaTeX and (2) in the SC variant of "Noto CJK" font
families, those UTF-8 symbols have full-width glyph.

The KR variant of the font families has half-width glyph for those
symbols and TOC pages should look nicer when it is used instead.

Switch the default CJK font families to the KR variant and teach
xeCJK of those symbols' widths.
To compensate the switch, teach xeCJK of the width in the SC and
TC variants.

Signed-off-by: Akira Yokosawa 
Cc: Jonathan Corbet 
Link: https://lore.kernel.org/r/0c8ea878-0a6f-ea01-ab45-4e66c5facee9@gmail.com
Signed-off-by: Jonathan Corbet

docs: pdfdocs: Tweak width params of TOC

2022-02-15T23:35:53+00:00

Sphinx has its own set of width parameters of Table of Contents (TOC)
for LaTeX defined in its class definition of sphinxmanual.cls.
It also inherits parameters for chapter entries from report.cls of
original LaTeX base.

However, they are optimized assuming small documents with tens of
pages and chapters/sections of less than 10.

To cope with some of kernel-doc documents with more than 1000
pages and several tens of chapters/sections, definitions of those
parameters need to be adjusted.

Unfortunately, those parameters are hard coded in the class
definitions and need low-level LaTeX coding tricks to redefine.

As Sphinx 1.7.9 does not have \sphinxtableofcontentshook,
which defines those parameters in later Sphinx versions,
for compatibility with both pre-1.8 and later Sphinx versions,
empty the hook altogether and redefine \@pnumwidth, \l@chapter,
\l@section, and \@subsection commands originally defined in
report.cls.

Summary of parameter changes:

  Width of page number (\@pnumwidth): 1.55em  -> 2.7em
  Width of chapter number:  1.5em -> 1.8em
  Indent of section number: 1.5em -> 1.8em
  Width of section number:  2.6em -> 3.2em
  Indent of subsection number: 4.1em -> 5em
  Width of subsection number:  3.5em -> 4.3em

Notes:
1. Parameters for subsection become relevant only when
   ":maxdepth: 3" is specified under "toctree::" (e.g., RCU/index.rst).
   They can hold subsection numbers up to 5 digits such as "18.7.13"
   (in RCU.pdf).

2. Number of chapters in driver-api.pdf is getting closer to 100.
   When it reaches 100, another set of tweaks will be necessary.

3. The low-level LaTeX trick is mentioned in "Unofficial LaTeX2e
   reference manual" at:
        http://latexref.xyz/Table-of-contents-etc_002e.html

Signed-off-by: Akira Yokosawa 
Cc: Jonathan Corbet 
Link: https://lore.kernel.org/r/e52b4718-7909-25be-fbc1-76800aa62ae3@gmail.com
Signed-off-by: Jonathan Corbet

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