linux-toradex.git/Documentation/doc-guide/sphinx.rst, branch v6.7

docs/doc-guide: Clarify how to write tables

2023-06-09T07:57:56+00:00

Prior to this commit, the kernel docs writing guide spent over a page
describing exactly how *not* to write tables into the kernel docs,
without providing a example about the desired format.

This patch provides a positive example first in the guide so that it's
harder to miss, then leaves the existing less desirable approach below
for contributors to follow if they have some stronger justification for
why to use that approach.

Signed-off-by: Joe Stringer 
Reviewed-by: Randy Dunlap 
Link: https://lore.kernel.org/r/20230424171850.3612317-1-joe@isovalent.com
Signed-off-by: Jonathan Corbet

docs: update sphinx.rst to reflect the default theme change

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

We don't default to Read The Docs anymore; update the docs to match.

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

docs/doc-guide: Add documentation on SPHINX_IMGMATH

2022-09-29T19:13:45+00:00

Now that building html docs with math expressions does not need texlive
packages, remove the note on the requirement in the "Sphinx Install"
section.

Instead, add sections of "Math Expressions in HTML" and "Choice of Math
Renderer".
Describe the effect of setting SPHINX_IMGMATH in the latter section.

Signed-off-by: Akira Yokosawa 
Cc: Mauro Carvalho Chehab 
Cc: Randy Dunlap 
Link: https://lore.kernel.org/r/a67e3279-6bc7-ee2c-2b49-9275252460b0@gmail.com
Signed-off-by: Jonathan Corbet

docs/doc-guide: Mention make variable SPHINXDIRS

2022-06-30T18:23:38+00:00

SPHINXDIRS is useful when you want to test build only those
documents affected by your changes.

Mention it in the "Sphinx Build" section.

Signed-off-by: Akira Yokosawa 
Cc: Maciej W. Rozycki 
Link: https://lore.kernel.org/r/50d6f0bc-030d-9529-0665-e2b3e7c792d8@gmail.com
Signed-off-by: Jonathan Corbet

docs/doc-guide: Add footnote on Inkscape for better images in PDF documents

2022-06-27T22:24:40+00:00

With kernel releases v5.18 and later, if you have Inkscape, images
embedded in PDF documents are of vector graphics, not the raster
images as are the case with pre-v5.18 releases.
Even with pre-5.18 releases, having Inkscape would improve images
converted from some of SVG files which are not fully covered by the
limited capability of rsvg-convert(1) [1].

Add a footnote mentioning the expected improvements of such images.

Link: https://gitlab.gnome.org/GNOME/librsvg#non-goals-of-librsvg [1]
Signed-off-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/81cddbde-bc28-bec1-fca4-3c8fe2df502f@gmail.com
Signed-off-by: Jonathan Corbet

Documentation: sphinx: replace "Introduction" chapter heading with page title

2022-04-05T16:00:43+00:00

Replace first chapter heading ("Introduction") with page title named
"Using Sphinx for kernel documentation". This way, the first-level TOC
for doc-guide contains title instead of chapter headings for this page.

Cc: Jonathan Corbet 
Cc: "David S. Miller" 
Cc: Greg Kroah-Hartman 
Cc: Tony Nguyen 
Cc: Vinod Koul 
Cc: Daniel Borkmann 
Cc: Mauro Carvalho Chehab 
Cc: Akira Yokosawa 
Cc: "Rafael J. Wysocki" 
Cc: Jens Axboe 
Cc: linux-kernel@vger.kernel.org
Reviewed-by: Mauro Carvalho Chehab 
Signed-off-by: Bagas Sanjaya 
Signed-off-by: Jonathan Corbet

docs: discourage use of list tables

2022-01-07T16:33:13+00:00

Our documentation encourages the use of list-table formats, but that advice
runs counter to the objective of keeping the plain-text documentation as
useful and readable as possible.  Turn that advice around the other way so
that people don't keep adding these tables.

Acked-by: Christoph Hellwig 
Acked-by: Randy Dunlap 
Signed-off-by: Jonathan Corbet

docs: address some text issues with css/theme support

2021-12-16T22:54:12+00:00

Fix:
- overriden ->overridden
- some whitespace issues introduced at the css/theme
  Makefile help.

Reported-by: Randy Dunlap 
Signed-off-by: Mauro Carvalho Chehab 
Reviewed-by: Randy Dunlap 
Link: https://lore.kernel.org/r/b0b166025019f7cc4f122bd789c79ba28cc2d29d.1639212812.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