Commit Graph

126 Commits

Author SHA1 Message Date
Daniel Vetter
e17f226038 docs/sphinx: More depth in the rtd sidebar toc
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 <daniel.vetter@intel.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20221108115707.1232621-1-daniel.vetter@ffwll.ch
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-11-09 13:28:40 -07:00
Jonathan Corbet
bd5d1cc8ff docs: Don't wire font sizes for HTML output
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 <bagasdotme@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-11-01 15:59:40 -06:00
Jonathan Corbet
02d33e8646 docs: decruft Documentation/conf.py
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 <mchehab@kernel.org>
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-10-18 16:29:35 -06:00
Jonathan Corbet
2056b920c6 docs: tweak some Alabaster style parameters
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 <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-10-13 11:14:31 -06:00
Jonathan Corbet
d5389d3145 docs: Switch the default HTML theme to alabaster
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 <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-10-13 11:14:12 -06:00
Jonathan Corbet
05fff6ba04 Merge branch 'docs-mw' into docs-next 2022-09-29 13:29:16 -06:00
Jonathan Corbet
3aa024e4e9 docs: reconfigure the HTML left column
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 <void@manifault.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20220927160559.97154-4-corbet@lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-09-29 12:55:06 -06:00
Jonathan Corbet
3ef859a4f6 Merge branch 'docs-mw' into docs-next 2022-09-27 13:23:18 -06:00
Akira Yokosawa
3b384e9564 docs/conf.py: Respect env variable SPHINX_IMGMATH
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 <akiyks@gmail.com>
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/5a582b2b-d51c-a062-36b2-19479cf68fab@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-09-27 13:21:43 -06:00
Akira Yokosawa
6b0d3e7c58 docs/conf.py: Treat mathjax as fallback math renderer
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 <akiyks@gmail.com>
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
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 <corbet@lwn.net>
2022-09-27 13:21:43 -06:00
Menglong Dong
5479d6d4bf docs/conf.py: add function attribute '__fix_address' to conf.py
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 <sfr@canb.auug.org.au>
Signed-off-by: Menglong Dong <imagedong@tencent.com>
Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-08-26 16:47:13 -06:00
Akira Yokosawa
627f01eab9 docs/conf.py: Cope with removal of language=None in Sphinx 5.0.0
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 <akiyks@gmail.com>
Link: https://lore.kernel.org/r/bd0c2ddc-2401-03cb-4526-79ca664e1cbe@gmail.com
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-06-01 09:26:05 -06:00
Akira Yokosawa
398f7abdcb docs: pdfdocs: Pull LaTeX preamble part out of conf.py
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 3b4c963243 ("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:

  - f7ebe6b769 ("docs: Activate exCJK only in CJK chapters")
  - 0afd4df0d1 ("docs: pdfdocs: Prevent column squeezing by tabulary")
  - 659653c9e5 ("docs: pdfdocs: Refactor config for CJK document")
  - e291ff6f5a ("docs: pdfdocs: Add CJK-language-specific font settings")
  - 7eb368cc31 ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible")
  - 35382965bd ("docs: pdfdocs: Preserve inter-phrase space in Korean translations")
  - 77abc2c230 ("docs: pdfdocs: One-half spacing for CJK translations")
  - 788d28a257 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts")
  - 29ac982235 ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks")
  - 7c5c18bdb6 ("docs: pdfdocs: Fix typo in CJK-language specific font settings")
  - aa872e0647 ("docs: pdfdocs: Adjust \headheight for fancyhdr")
  - 8716ef413a ("docs: pdfdocs: Tweak width params of TOC")
  - 66939df539 ("docs: pdfdocs: Switch default CJK font to KR variants")
  - 7b686a2ea1 ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles")
  - 5d9158e3c7 ("docs/translations: Skip CJK contents if suitable fonts not found")
  - b774cc4631 ("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 <corbet@lwn.net>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-24 12:26:13 -07:00
Akira Yokosawa
b774cc4631 docs: pdfdocs: Move CJK monospace font setting to main conf.py
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 a90dad8f61 ("docs: pdfdocs: Add conf.py
local to translations for ascii-art alignment").

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/eb87790a-03f4-9f29-c8a3-ef2c3e78ca18@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-15 16:35:54 -07:00
Akira Yokosawa
5d9158e3c7 docs/translations: Skip CJK contents if suitable fonts not found
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 <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/3359ca41-b81d-b2c7-e437-7618efbe241d@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-15 16:35:54 -07:00
Akira Yokosawa
7b686a2ea1 docs: pdfdocs: Enable CJKspace in TOC for Korean titles
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 <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/19141b3e-01d9-1f6d-5020-42fbda784831@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-15 16:35:53 -07:00
Akira Yokosawa
66939df539 docs: pdfdocs: Switch default CJK font to KR variants
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 <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0c8ea878-0a6f-ea01-ab45-4e66c5facee9@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-15 16:35:53 -07:00
Akira Yokosawa
8716ef413a docs: pdfdocs: Tweak width params of TOC
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 <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e52b4718-7909-25be-fbc1-76800aa62ae3@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-02-15 16:35:53 -07:00
Mauro Carvalho Chehab
a6fb8b5acf docs: add support for RTD dark mode
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 <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/90d316e055ef7f4c9021b9eada8f8d3b2e750a66.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-12-10 14:05:55 -07:00
Mauro Carvalho Chehab
ffc901b4d1 docs: set format for the classic mode
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 <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/8889380606681a2b7033f73bed9717250302be2a.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-12-10 14:05:55 -07:00
Mauro Carvalho Chehab
135707d376 docs: allow to pass extra DOCS_CSS themes via make
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 <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/03d09bf41ad39aa0abfe2ea3c879b09aa3a0948d.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-12-10 14:05:55 -07:00
Mauro Carvalho Chehab
fca7216bf5 docs: allow selecting a Sphinx theme
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 <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/bd20adabfd428fd3cd0e69c2cf146aa354932936.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-12-10 14:05:55 -07:00
Mauro Carvalho Chehab
d69dab7de2 docs: conf.py: fix support for Readthedocs v 1.0.0
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 <hverkuil@xs4all.nl>
Tested-by: Hans Verkuil <hverkuil@xs4all.nl>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/80009f0d17ea0840d81e7e16fff6e7677919fdfc.1638004294.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-11-29 14:27:52 -07:00
Akira Yokosawa
aa872e0647 docs: pdfdocs: Adjust \headheight for fancyhdr
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 <akiyks@gmail.com>
Link: https://lore.kernel.org/r/c5a5577e-5de8-9cd4-9253-956ccc748417@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-10-12 14:09:03 -06:00
Akira Yokosawa
7c5c18bdb6 docs: pdfdocs: Fix typo in CJK-language specific font settings
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: e291ff6f5a ("docs: pdfdocs: Add CJK-language-specific font settings")
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/ad7615a5-f8fa-2bc3-de6b-7ed49d458964@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-09-06 16:53:39 -06:00
Akira Yokosawa
29ac982235 docs: pdfdocs: Teach xeCJK about character classes of quotation marks
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 <akiyks@gmail.com>
Link: https://lore.kernel.org/r/0da9e3c5-2716-f576-1df5-2f28ea69f0e8@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:33 -06:00
Akira Yokosawa
788d28a257 docs: pdfdocs: Permit AutoFakeSlant for CJK fonts
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 <akiyks@gmail.com>
Link: https://lore.kernel.org/r/502335cc-9a95-3c2a-7744-6cc56ecaf628@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:33 -06:00
Akira Yokosawa
77abc2c230 docs: pdfdocs: One-half spacing for CJK translations
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 <akiyks@gmail.com>
Link: https://lore.kernel.org/r/547a1f1c-0bb5-20a7-ea0e-951bfc3c3925@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:32 -06:00
Akira Yokosawa
35382965bd docs: pdfdocs: Preserve inter-phrase space in Korean translations
In Korean typesetting, inter-phrase spaces in Hangul text have
a similar role as the the inter-word spaces in Latin text.
They can be preserved by the \xeCJKsetup{CJKspace=true} option.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/68de2e52-e6d1-3f01-c097-15ba7b28a319@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:32 -06:00
Akira Yokosawa
7eb368cc31 docs: pdfdocs: Choose Serif font as CJK mainfont if possible
"Noto Serif CJK SC" and its variants suit better with the roman font
of Latin letters.

On some distros such as Fedora, it is possible to partially install
"Noto Sans CJK" fonts.
So, if the Serif fonts are not found on the system, fall back to the
Sans fonts.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/5e454140-5d0c-35d4-8c31-3ffb2420793a@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:32 -06:00
Akira Yokosawa
e291ff6f5a docs: pdfdocs: Add CJK-language-specific font settings
zh_TW, ko_KR, and ja_JP translations have their preferred glyph sets
different from that of zh_CN.

To switch CJK font in the middle of the translations, introduce custom
LaTeX macros listed below:

    \kerneldocBeginSC
    \kerneldocEndSC
    \kerneldocBeginTC
    \kerneldocEndTC
    \kerneldocBeginKR
    \kerneldocEndKR
    \kerneldocBeginJP
    \kerneldocEndJP

, and embed a pair of macros in each language's index.rst.

NOTE 1: Update of zh_TW/index.rst is deferred to a follow-up change.

NOTE 2: Custom macros added here do not imply \kerneldocCJK(on|off).
This is intentional.  For example, \kerneldocCJKoff needs to be
at the top of Italian translations' index.rst for the footer of
final zh_TW page to be properly typeset.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/31906baf-7490-68cd-7153-4e4d320fb9b0@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:32 -06:00
Akira Yokosawa
659653c9e5 docs: pdfdocs: Refactor config for CJK document
To make generated LaTeX code portable across systems with different sets
of available fonts, convert font-availability check in python code to
LaTeX code by using a conditional command provided by the "fontspec"
package.

This will help those who run Sphinx on one machine/container and run
latexmk on other machines/containers.

Remove import of check_output as it is unused any more.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/4baf88af-316d-8aee-240f-6ccbc20907d7@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-08-12 09:13:32 -06:00
Jonathan Corbet
102caec107 docs: Take a little noise out of the build process
Sphinx 3.0 works at this point (albeit slowly) so stop scaring people
with a loud warning.  We also don't need to babble about CJK support in the
LaTeX build.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-06-17 13:49:18 -06:00
Akira Yokosawa
0afd4df0d1 docs: pdfdocs: Prevent column squeezing by tabulary
Setting a reasonable width to \tymin prevents column squeezing
by tabulary.
Width of 20em works well in almost all the tables still in the
ascii-art format.

Excerpt from tabulary package documentation at [1]:

    To stop very narrow columns being too 'squeezed' by this process
    any columns that are narrower than \tymin are set to their natural
    width.

[1]: https://mirrors.ctan.org/macros/latex/contrib/tabulary/tabulary.pdf

Note: Sphinx has its own default value of \tymin set in
sphinxlatextables.sty (Sphinx 4.0.2) and sphinxmulticell.sty
(Sphinx 2.4.4) as follows:

    \setlength{\tymin}{3\fontcharwd\font`0 }

, which is not sufficient for kernel-doc.

Tested against Sphinx versions 2.4.4 and 4.0.2.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/277d68fa-c96a-0ccb-6ce0-4d314851d9fe@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-06-01 16:49:52 -06:00
Akira Yokosawa
f7ebe6b769 docs: Activate exCJK only in CJK chapters
Activating xeCJK in English and Italian-translation documents
results in sub-optimal typesetting with wide-looking apostrophes
and quotation marks.

The xeCJK package provides macros for enabling and disabling its
effect in the middle of a document, namely \makexeCJKactive and
\makexeCJKinactive.

So the goal of this change is to activate xeCJK in the relevant
chapters in translations.

To do this:

    o Define custom macros in the preamble depending on the
      availability of the "Noto Sans CJK" font so that those
      macros can be used regardless of the use of xeCJK package.

    o Patch \sphinxtableofcontents so that xeCJK is inactivated
      after table of contents.

    o Embed those custom macros in each language's index.rst file
      as a ".. raw:: latex" construct.

Note: A CJK chapter needs \kerneldocCJKon in front of its chapter
heading, while a non-CJK chapter should have \kerneldocCJKoff
below its chapter heading.

This is to make sure the CJK font is available to CJK chapter's
heading and ending page's footer.

Tested against Sphinx versions 2.4.4 and 4.0.2.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Tested-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/lkml/2061da0a-6ab1-35f3-99c1-dbc415444f37@gmail.com
Link: https://lore.kernel.org/r/83208ddc-5de9-b283-3fd6-92c635348ca0@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-05-27 09:59:41 -06:00
Mauro Carvalho Chehab
3b4c963243 docs: conf.py: adjust the LaTeX document output
Changeset f546ff0c0c ("Move our minimum Sphinx version to 1.7")
cleaned up some compatibility issues with previous Sphinx
versions, but it also dropped the PDF margin sets.

Without that, the media documentation won't build fine, as
the margins are too wide to display texts with monospaced
fonts.

While here, align the  "latex_elements = {" values, and add
a few other sphinxsetup configs in order to allow Sphinx to
wrap long lines on literal blocks.

Fixes: f546ff0c0c ("Move our minimum Sphinx version to 1.7")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

 Documentation/conf.py | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)
Link: https://lore.kernel.org/r/911fbac185dd09c7df715cf4153361b81f04b7ad.1614787053.git.mchehab+huawei@kernel.org

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-03-08 17:20:03 -07:00
Matthew Wilcox
36d8900d20 Fix unaesthetic indentation
The current documentation build looks like this:

$ make htmldocs
  SPHINX  htmldocs --> file:///home/willy/kernel/linux-next/Documentation/output
make[2]: Nothing to be done for 'html'.
WARNING: The kernel documentation build process
        support for Sphinx v3.0 and above is brand new. Be prepared for
        possible issues in the generated output.
        $

That extra indentation before my next prompt isn't pretty.  This patch
fixes it, but I'm not a pythonista, and maybe there's a better way.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
Link: https://lore.kernel.org/r/20210215161757.GD2858050@casper.infradead.org
[jc: tweaked for the "better way"]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-02-22 14:35:04 -07:00
Jonathan Corbet
f546ff0c0c Move our minimum Sphinx version to 1.7
As promised, drop support for some ancient sphinx releases, along with a
lot of the cruft that was required to make that support work.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-02-01 16:29:12 -07:00
Jonathan Corbet
13fef8ef9f docs: Note that sphinx 1.7 will be required soon
The time has come to drop support for some truly ancient versions of
sphinx; put in a warning now.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-12-11 13:53:38 -07:00
Mauro Carvalho Chehab
63fdc4625a docs: admin-guide: add a features list
Add a feature list matrix at the admin-guide.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/f6c1e366fbc7ce1c9c94c7dc6c7852c6377cc0be.1606748711.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-12-03 15:10:15 -07:00
Linus Torvalds
e6b0bd61a7 This pull contains a series of warning fixes from Mauro; once applied, the
number of warnings from the once-noisy docs build process is nearly zero.
 Getting to this point has required a lot of work; once there, hopefully we
 can keep things that way.
 
 I have packaged this as a separate pull because it does a fair amount of
 reaching outside of Documentation/.  The changes are all in comments and in
 code placement.  It's all been in linux-next since last week.
 -----BEGIN PGP SIGNATURE-----
 
 iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAl+hscQPHGNvcmJldEBs
 d24ubmV0AAoJEBdDWhNsDH5YgZAH/0JeDA/1VLZYYTmdABz8mjBZsoW9tyPGGztF
 nsh5ykdHhL3MeTRwumW5armLVrfKhd1XT+nIzD7OcWlqu+RDOvQ5I95rahr473hP
 1SHTjqm3/AlJwQoeS72X5U6QEJQ58e2IwCbP23H3x7I3Q3snEA/HhswzxurfoB/Z
 j81YzDV2YPEc0LJWZ5Vn0NEdwP8cdpFv5rojsQmepq7K0yJ7tEHb7/u2cEuUBgXS
 8LcYCNPLpiN+q5N8uQ5oDjIUNdLQvP03kgKtQWiCTr4BRydOrDlJie28LIedamEz
 anu7UfaVK4bxn+ugRI0g2+aWQKux81ULCinKUWmLRNbcxjhaQqQ=
 =hDfp
 -----END PGP SIGNATURE-----

Merge tag 'docs-5.10-warnings' of git://git.lwn.net/linux

Pull documentation build warning fixes from Jonathan Corbet:
 "This contains a series of warning fixes from Mauro; once applied, the
  number of warnings from the once-noisy docs build process is nearly
  zero.

  Getting to this point has required a lot of work; once there,
  hopefully we can keep things that way.

  I have packaged this as a separate pull because it does a fair amount
  of reaching outside of Documentation/. The changes are all in comments
  and in code placement. It's all been in linux-next since last week"

* tag 'docs-5.10-warnings' of git://git.lwn.net/linux: (24 commits)
  docs: SafeSetID: fix a warning
  amdgpu: fix a few kernel-doc markup issues
  selftests: kselftest_harness.h: fix kernel-doc markups
  drm: amdgpu_dm: fix a typo
  gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups
  drm: amdgpu: kernel-doc: update some adev parameters
  docs: fs: api-summary.rst: get rid of kernel-doc include
  IB/srpt: docs: add a description for cq_size member
  locking/refcount: move kernel-doc markups to the proper place
  docs: lockdep-design: fix some warning issues
  MAINTAINERS: fix broken doc refs due to yaml conversion
  ice: docs fix a devlink info that broke a table
  crypto: sun8x-ce*: update entries to its documentation
  net: phy: remove kernel-doc duplication
  mm: pagemap.h: fix two kernel-doc markups
  blk-mq: docs: add kernel-doc description for a new struct member
  docs: userspace-api: add iommu.rst to the index file
  docs: hwmon: mp2975.rst: address some html build warnings
  docs: net: statistics.rst: remove a duplicated kernel-doc
  docs: kasan.rst: add two missing blank lines
  ...
2020-11-03 13:14:14 -08:00
Mauro Carvalho Chehab
a7ee04b3ef docs: add ABI documentation to the admin-guide book
As we don't want a generic Sphinx extension to execute commands,
change the one proposed to Markus to call the abi_book.pl
script.

Use a script to parse the Documentation/ABI directory and output
it at the admin-guide.

Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/5651482b06500e69a1acdf92152f90a203e6521d.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
2020-10-30 13:07:01 +01:00
Mauro Carvalho Chehab
d29f34c098 sphinx: conf.py: properly handle Sphinx 4.0
One of the checks for Sphinx 3+ is broken, causing some
C warnings to return back with Sphinx 4.0.x.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/d5abc30056dafeec0778a46263a45401bdc7f11e.1603791716.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-10-28 11:26:10 -06:00
Mauro Carvalho Chehab
14059a38a4 docs: conf.py: change the Sphinx 3.x+ text
After the build fix patches, it is believed that the output
with Sphinx 3.x won't be a problem. Still, the C domain
support was re-written, and this can have caused hidden
issues.

So, let's keep the warning, changing it to a lighter
warning text.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15 07:49:45 +02:00
Mauro Carvalho Chehab
b34b86d7a4 docs: conf.py: fix c:function support with Sphinx 3.x
Sphinx C parser for the C domain is now more pedantic when
trying to identify the function types. That prevents scope
macros to be used as type defines.

Yet, since 3.0.2, it is possible to provide it a list of
such macros. Add them, in order to solve several Sphinx 3.x
warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2020-10-15 07:49:45 +02:00
Jonathan Corbet
afde706afd Make the docs build "work" with Sphinx 3.x
The Sphinx 3.x upgrade broke a number of things in our special "cdomain"
module that are not easy to fix.  For now, just disable that module for the
3.x build and put out a warning that the build will not be perfect.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-09-04 10:13:45 -06:00
Alexander A. Klimov
93431e0607 Replace HTTP links with HTTPS ones: documentation
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.

Deterministic algorithm:
For each file:
  For each line:
    If doesn't contain `\bxmlns\b`:
      For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
        If both the HTTP and HTTPS versions
        return 200 OK and serve the same content:
          Replace HTTP with HTTPS.

Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-06-08 09:30:19 -06:00
Mauro Carvalho Chehab
25813cae1e docs: LaTeX/PDF: drop list of documents
The building system can auto-generate a list of documents since
commit: 9d42afbe6b ("docs: pdf: add all Documentation/*/index.rst to PDF output").

The added logic there allows keeping the existing list, but
there's not real reason to keep it. Now, the media document
has gone (it was split into tree).

So, it sounds about time to get rid of the manual entries,
and let the script to generate it automatically instead.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/9345dba7164497dbf28578f6ec271e479379610c.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20 15:35:58 -06:00
Mauro Carvalho Chehab
4658b0eb94 docs: conf.py: avoid thousands of duplicate label warning on Sphinx
The autosectionlabel extension is nice, as it allows to refer to
a section by its name without requiring any extra tag to create
a reference name.

However, on its default, it has two serious problems:

1) the namespace is global. So, two files with different
   "introduction" section would create a label with the
   same name. This is easily solvable by forcing the extension
   to prepend the file name with:

	autosectionlabel_prefix_document = True

2) It doesn't work hierarchically. So, if there are two level 1
   sessions (let's say, one labeled "open" and another one "ioctl")
   and both have a level 2 "synopsis" label, both section 2 will
   have the same identical name.

   Currently, there's no way to tell Sphinx to create an
   hierarchical reference like:

		open / synopsis
		ioctl / synopsis

  This causes around 800 warnings. So, the fix should be to
  not let autosectionlabel to produce references for anything
  that it is not at a chapter level within any doc, with:

	autosectionlabel_maxdepth = 2

Fixes: 58ad30cf91 ("docs: fix reference to core-api/namespaces.rst")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-03-20 17:01:34 -06:00
Jonathan Corbet
58ad30cf91 docs: fix reference to core-api/namespaces.rst
Fix a couple of dangling links to core-api/namespaces.rst by turning them
into proper references.  Enable the autosection extension (available since
Sphinx 1.4) to make this work.

Co-developed-by: Federico Vaga <federico.vaga@vaga.pv.it>
Fixes: fcfacb9f83 ("doc: move namespaces.rst from kbuild/ to core-api/")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-03-19 12:52:01 -06:00