It is best to point to the original line of code that generated
an error than to point to the beginning of a directive.
Add support for it. It should be noticed that this won't work
for literal or code blocks, as Sphinx will ignore it, pointing
to the beginning of the directive. Yet, when the output is known
to be in ReST format, like on TOC, this makes the error a lot
more easier to be handled.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a0953af8b71e64aaf2e0ba4593ad39e19587d50a.1755872208.git.mchehab+huawei@kernel.org
When generate-cross-refs is used, instead of just implementing
the default of generating a literal block, we can also
generate a ReST file as a TOC.
The advantage is that, by being a ReST file, missing references
will point to the place inside the header file that has the
broken link.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/c0d32cd1ef94017e05984b0a38bd2516f7db21e2.1755872208.git.mchehab+huawei@kernel.org
Originally, parse-readers were generating an output where
the first two lines were setting a literal block.
The script now gets only the actual parsed data without that,
so it is now safe to allow start-line and end-line parameters
to be handled.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/5dff693860a6a3faade15c24abdc380f09db468d.1755872208.git.mchehab+huawei@kernel.org
In the past, Sphinx used to warn about broken references. That's
basically the rationale for adding media uAPI files: to get
warnings about missed symbols.
This is not true anymore. So, we need to explicitly check them
after doctree-resolved event.
While here, move setup() to the end, to make it closer to
what we do on other extensions.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/73be9a198746421687e2eee916ccf8bf67980b7d.1755872208.git.mchehab+huawei@kernel.org
kernel_include extension was originally designed to be used by the
media comprehensive uAPI documentation, where, instead of simpler
kernel-doc markups, the uAPI documentation is enriched with a larger
text, with images, complex tables, graphs, etc.
There, we wanted to include the much simpler yet documented .h
file.
This extension is needed to include files from other parts of the
Kernel tree outside Documentation, because the original Sphinx
include tag doesn't allow going outside of the directory passed
via sphinx-build command line.
Yet, the cross-references themselves to the full documentation
were using a perl script to create cross-references against the
comprehensive documentation.
As the perl script is now converted to Phython and there is a
Python class producing an include-compatible output with cross
references, add two optional arguments to kernel_include.py:
1. :generate-cross-refs:
If present, instead of reading the file, it calls ParseDataStructs()
class, which converts C data structures into cross-references to
be linked to ReST files containing a more comprehensive documentation;
Don't use it together with :start-line: and/or :end-line:, as
filtering input file line range is currently not supported.
2. :exception-file:
Used together with :generate-cross-refs:. Points to a file containing
rules to ignore C data structs or to use a different reference name,
optionally using a different reference type.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/efc39c8e54a2056ae2fdb94d5006fcb19e227198.1755872208.git.mchehab+huawei@kernel.org
When running it from command line, we want to write an output
file, but when used as a class, one may just want the output
content returned as a string.
Split write_output() on two methods to allow both usecases.
Also add an extra method to produce a TOC.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/c98bdec3380aad54178baf2751a2f1fcd128576b.1755872208.git.mchehab+huawei@kernel.org
As suggested by Jon, we should start having a tools/docs
directory, instead of placing everything under scripts.
In the specific case of parse-headers.py, the previous
location is where we're placing Sphinx extensions, which is
not the right place for execs.
Move it to tools/docs/parse-headers.py.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0f5ac2d704cffe9834e589b39549d2393e1237ef.1755872208.git.mchehab+huawei@kernel.org
Normal :ref domain accept either hashes or underscores, but
c-domain ones don't. Fix it and remove unneeded places where
we opt to disable underscore transformation.
Ideally, we should have a rule about the default, or change
the way media docs have their references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0c011090272f7a1068545409222f970ddb1ed431.1755872208.git.mchehab+huawei@kernel.org
The kernel-doc markups inside headers may contain @var markups.
With the current rule, this would be converted into:
\* @:c:type:`DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR <dmx_buffer_flags>`\:
Fix it adding a non-printed space if needed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/8d06bb713d6ec8de65179dd93defe479715409b6.1755872208.git.mchehab+huawei@kernel.org
When printing --help, we'd like the name of the files
from __doc__ to match the displayed positional arguments at
both usage and argument description lines.
Use a custom formatter class to convert ``foo`` into ANSI SGR
code to bold the argument, if is TTY, and adjust the help
text to match the argument names.
Here on Plasma, that makes it display it colored, wich is
really cool. Yet, I opted for SGR, as the best is to follow
the terminal color schema for bold.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/2c1e61d1fb1b2a2838b443beee89c1528831997f.1755872208.git.mchehab+huawei@kernel.org
When the Kernel started to use Sphinx, we had to come up with
a solution to parse media headers. On that time, we didn't have
much experience with Sphinx extensions. So, we came up with our
own script-based solution that were basically implementing a
set of rules we used to have at the Makefile.
Convert it to Python, keeping it bug-compatible with the
original script.
While here, try to better document it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/ae5cfa8dff37e280cc9493fc95a51cd0cc0ba127.1755872208.git.mchehab+huawei@kernel.org
Some of texts in filecheck operations list are indented out of the list.
In particular, the third operation is shown not as the third list
item but rather as a separate paragraph.
Reindent the list so that gets properly rendered as such.
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Acked-by: Joseph Qi <joseph.qi@linux.alibaba.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250826024756.16073-1-bagasdotme@gmail.com
Replace FIXME comments in the pinctrl documentation example with
proper cleanup code:
- Add devm_pinctrl_put() calls in error paths
(pinctrl_lookup_state, pinctrl_select_state)
after successful devm_pinctrl_get()
- Set foo->p to NULL when devm_pinctrl_get() fails
- Add ret variable for cleaner error handling
- provides proper example of pinctrl resource management on failure
Signed-off-by: Alex Tran <alex.t.tran@gmail.com>
Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250827074525.685863-1-alex.t.tran@gmail.com
Here it is the second version of the PDF series. I opted to split one of
the patches in 3, to have a clearer changelog and description.
Also, archlinux LXC image download started working again, so I added
an extra patch addressing texlive packae dependencies.
This series is taking me a way more time than antecipated.
This series as 3 goals:
1. Fix a pre-Sphinx 1.7 PDF variable that got renamed, but
our Makefile still uses the old one that is not supported
since Sphinx 1.7;
2. Fix broken or incomplete texlive dependencies on several
distros;
4. "modernize" conf.py to solve font conflicts related to UTF-8
and non-UTF fonts from [T1]{fontenc} LaTeX package.
Using fontenc with xelatex is problematic, as documented at
https://www.sphinx-doc.org/en/master/latex.html
Please notice that:
- It doesn't pretend to fix all PDF issues. It focus only at the
above;
- there are still distros where PDF builds fail either partially
or as a hole. On my checks, those are due to problematic
texlive packages shipped on such distros;
- it doesn't touch/address/alter anyhing related to kfigure.py.
as such, it doesn't touch/change/improve/drop anything with
regards ImageMagick and/or Inkscape.
There are some missing packages causing PDF build to fail on
Archlinux and add latexmk (from texlive-binextra package).
Yet, at least today, PDF builds are failing on a very late
stage, when trying to run xdvipdfmx:
$ xdvipdfmx -E -o "peci.pdf" "peci.xdv"
xdvipdfmx:fatal: Unrecognized paper format: # Simply write the paper name. See man 1 paper and "paper --no-size --all" for possible values
Despite its message, even using a very simple document like:
\def\sphinxdocclass{report}
\documentclass[a4paper,11pt,english]{sphinxmanual}
\begin{document}
Test
\end{document}
or even:
\def\sphinxdocclass{report}
\documentclass{sphinxmanual}
\begin{document}
Test
\end{document}
Is causing xdvipdfmx to complain about geometry. As Archlinux is
a rolling release distro, maybe I got it on a bad day. So, let's
fix it in the hope that soon enough someone would fix the issues
there.
Such broken scenario happens with those packages installed:
texlive-basic 2025.2-1
texlive-bin 2025.2-1
texlive-binextra 2025.2-1
texlive-fontsrecommended 2025.2-1
texlive-langchinese 2025.2-1
texlive-langcjk 2025.2-1
texlive-latex 2025.2-1
texlive-latexextra 2025.2-1
texlive-latexrecommended 2025.2-1
texlive-pictures 2025.2-1
texlive-xetex 2025.2-1
python-docutils 1:0.21.2-3
python-sphinx 8.2.3-1
python-sphinx-alabaster-theme 1.0.0-4
python-sphinxcontrib-applehelp 2.0.0-3
python-sphinxcontrib-devhelp 2.0.0-4
python-sphinxcontrib-htmlhelp 2.1.0-3
python-sphinxcontrib-jsmath 1.0.1-19
python-sphinxcontrib-qthelp 2.0.0-3
python-sphinxcontrib-serializinghtml 2.0.0-3
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/574d902f7691861e18339217f42409850ee58791.1755763127.git.mchehab+huawei@kernel.org
The dependeny list for OpenMandriva is wrong. Update it.
Yet, on my tests with OpenMandriva LX 4.3, the texlive packages are
broken: xelatex can't build anything there, as it lacks xelatex.sfm.
Yet, this could be a problem at the way I created the container.
Just in case, add a note about that.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/669e759ba366328e5c8d5b14a591ba45a1f58176.1755763127.git.mchehab+huawei@kernel.org
The dependencies are outdated: both versions need texlive-dejavu
fonts. Also, for PDF generation, python311-Sphinx-latex is
required.
With that, all PDF files are now tuilt on both:
openSUSE Leap 15.6:
-------------------
PASSED: OS detection: openSUSE Leap 15.6
SKIPPED (Sphinx Sphinx 7.2.6): System packages
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 5:29, return code: 0
PASSED: Build PDF documentation: Build time: 13:45, return code: 0
openSUSE Tumbleweed:
--------------------
PASSED: OS detection: openSUSE Tumbleweed
SKIPPED (Sphinx Sphinx 8.2.3): System packages
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv
SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package
PASSED: Clean documentation: Build time: 0:00, return code: 0
PASSED: Build HTML documentation: Build time: 4:33, return code: 0
PASSED: Build PDF documentation: Build time: 13:18, return code: 0
Summary
=======
PASSED - openSUSE Leap 15.6 (7 tests)
PASSED - openSUSE Tumbleweed (7 tests)
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/d78457376f9dfd24cb7ac3a32895c654412715f3.1755763127.git.mchehab+huawei@kernel.org
Makes it more adehent with modern Sphinx LaTeX build setup as
defined at:
https://www.sphinx-doc.org/en/master/latex.html
There, it suggests:
1) to add: 'printindex'
“printindex” call, the last thing in the file. Override if you want to generate
the index differently, append some content after the index, or change the font.
As LaTeX uses two-column mode for the index it is often advisable to set this
key to r'\footnotesize\raggedright\printindex'.
This indeed solved a corner case on a distro where the index was not properly
generated.
2) to add at the main example:
\PassOptionsToPackage{svgnames}{xcolor}
3) I got a corner case on one of the distros was using xindy to produce
indexes. This ended causing the build logic to incorretly try to use
T1 fontenc, which is not UTF-8 compatible.
This patch adds:
\PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic}
to cover such case. It should be noticed that, as the config doesn't
have \usepackage{xindy}, this will be used only if latexmk ends
using xindy.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/08d16c2ad817910eb5606842f776d3f77d83282f.1755763127.git.mchehab+huawei@kernel.org
While PDF docs work fine on RPM-based distros, it causes conflicts
on Debian & friends.
There are multiple root causes here:
- the latex_elements still resambles the one from Sphinx 1.x
times, where font configurations were stored under
"preamble". It doesn't follow the current recommended way from
Sphinx documentation:
https://www.sphinx-doc.org/en/master/latex.html
- instead of setting the main font, from where other fonts are
derivated, it sets romanfont;
- "fontenc" is not set. This allows the *.tex output file to
contain an UTF-8 incompatible fontset:
\usepackage[T1]{fontenc}
Address such issues to help preventing incompatible usage of
both T1 font and UTF-8 ones that comes from DejaVu font
family.
On some distros, this even generate a LaTeX font warning about
corrupted NFSS tables like this (I got it when running it in
interactive mode):
Package: fontenc 2021/04/29 v2.0v Standard LaTeX package
LaTeX Font Info: Trying to load font information for T1+lmr on input line 11
6.
LaTeX Font Info: No file T1lmr.fd. on input line 116.
LaTeX Font Warning: Font shape `T1/lmr/m/n' undefined
(Font) using `T1/lmr/m/n' instead on input line 116.
! Corrupted NFSS tables.
wrong@fontshape ...message {Corrupted NFSS tables}
error@fontshape else let f...
l.116 ...\familydefault\seriesdefault\shapedefault
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/8104ce56a5ea3509fbb56a8163b779d38a6aaa9c.1755763127.git.mchehab+huawei@kernel.org
Instead of adding extra weird indentation at the tex
file, use dedent(). While here, also use r-strings, to make
easier to make its content identical to the .tex output.
While here, also merge "preamble" that was added on two
separate parts of the code (in the past, there were some
version-specific checks).
No functional changes, just cosmetic ones.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0d245fbd872ab3ec21bd8fe78b01340ba77ce365.1755763127.git.mchehab+huawei@kernel.org
Currently, the logic uses fn and doc vars, but they don't
properly describe what such vars do.
Make them clearer:
- fname: points to the file name to search (index.rst);
- doc: contains the name of the LaTeX or PDF doc to
be produced.
With that, the checks for SPHINXDIRS and for subdirs will
be more coherent.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/b030d9bc53550905adbe9367b2a3915d7331b4c5.1755763127.git.mchehab+huawei@kernel.org
When SPHINXDIRS is used, the current logic produces a wrong
list of files, as it will not pick the SPHINXDIRS directory,
picking instead their children.
Add a rule to detect it and create the PDF doc with the right
name.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/183f630643eacf414cfa8d892f03dd1b1055c21e.1755763127.git.mchehab+huawei@kernel.org
The original logic assumed that app.srcdir is identical to the
current working dir. This is the case for a normal build, but,
when SPHINXDIRS="some dir" is used, this is not the case anymore.
Adjust the logic to fill the LaTeX documents considering
app.srcdir, in a way that it will work properly on all cases.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/de23b35a770210950c609deaa32b98cb3673a53a.1755763127.git.mchehab+huawei@kernel.org
The documents explain the design concepts behind PREEMPT_RT and highlight key
differences necessary to achieve it.
It also include a list of requirements that must be fulfilled to support
PREEMPT_RT on a given architecture.
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
[jc: tweaked "how they differ" section head]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250815093858.930751-4-bigeasy@linutronix.de
local_lock_nested_bh() is used within networking where applicable.
Document why it is used and how it behaves.
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250815093858.930751-3-bigeasy@linutronix.de
Add a SPDX identifier. The majority of the document has been written by
Ahmed S. Darwish.
Cc: Ahmed S. Darwish <darwi@linutronix.de>
Acked-by: Ahmed S. Darwish <darwi@linutronix.de>
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250815093858.930751-2-bigeasy@linutronix.de
in Documentation/filesystems/propagate_umount.txt:
line 289: remove whitespace on blank line
line 315: remove duplicate "that"
line 364: remove duplicate "in"
Signed-off-by: Raphael Pinsonneault-Thibeault <rpthibeault@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250818181934.55491-2-rpthibeault@gmail.com
Add a few missing directories under /proc/sys.
Fix punctuation and doubled words.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Rik van Riel <riel@surriel.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Reviewed-by: Rik van Riel <riel@surriel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250819075456.113623-1-rdunlap@infradead.org
-Changed 'Dyamically' to 'Dynamically' in trace/events.rst
under sections 7.1 and 7.3
Signed-off-by: Mehdi Ben Hadj Khelifa <mehdi.benhadjkhelifa@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250819085040.974388-1-mehdi.benhadjkhelifa@gmail.com
Fix documentation issues by removing a duplicated word and adding the
missing SPDX-License identifier.
Signed-off-by: Bartlomiej Kubik <kubik.bartlomiej@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250819113551.34356-1-kubik.bartlomiej@gmail.com
toctree index in USB driver api docs currently spoils the entire docs
headings due to lack of :maxdepth: option. Add the option to limit
toctree depth to 1, mirroring usb subsystem docs in
Documentation/usb/index.rst.
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250820050416.25219-1-bagasdotme@gmail.com
Reiserfs has been removed in 6.13, there are still some mentions in the
documentation about it and the tools. Remove those that don't seem
relevant anymore but keep references to reiserfs' r5 hash used by some
code.
There's one change in a script scripts/selinux/install_policy.sh but it
does not seem to be relevant either.
Signed-off-by: David Sterba <dsterba@suse.com>
Acked-by: Paul Moore <paul@paul-moore.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250813100053.1291961-1-dsterba@suse.com
