kernel/linux.git/Documentation/sphinx/kernel_include.py, branch v6.18.21

docs: kdoc: handle the obsolescensce of docutils.ErrorString()

2025-09-15T23:24:06+00:00

The ErrorString() and SafeString() docutils functions were helpers meant to ease the handling of encodings during the Python 3 transition. There is no real need for them after Python 3.6, and docutils 0.22 removes them, breaking the docs build Handle this by just injecting our own one-liner version of ErrorString(), and removing the sole SafeString() call entirely. Reported-by: Zhixu Liu Signed-off-by: Jonathan Corbet Message-ID: <87ldmnv2pi.fsf@trenco.lwn.net>

docs: kernel_include.py: drop some old behavior

2025-09-01T13:33:59+00:00

The old behavior is not using anymore, so let's drop it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/00cdf3cbe2481aac875c543ded14b5eacfe071ec.1756732363.git.mchehab+huawei@kernel.org

docs: kernel_include.py: fix an issue when O= is used

2025-09-01T13:33:59+00:00

As reported by Stephen, building docs with O= is now broken. Fix it by ensuring that it will seek files under Kernel source tree. The original logic was defined to accept including files under Documentation/output. The new logic doesn't need it anymore for media, but it might still be useful to preserve the previous behavior. So, I ended preserving it. Reported-by: Stephen Rothwell Closes: https://lore.kernel.org/all/20250901142639.4de35a11@canb.auug.org.au/ Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/da91980ce42f31730dc982920167b2757b9d2769.1756732363.git.mchehab+huawei@kernel.org

docs: kernel_include.py: document all supported parameters

2025-08-29T21:54:43+00:00

As we're actually a fork of Sphinx Include, update its docstring to contain the documentation for the actual implemented parameters. Let's use :param: for parameters, as defined at: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/f193160889a2dc296b4df2cc7ebc9934d717ccef.1755872208.git.mchehab+huawei@kernel.org

docs: kernel_include.py: remove Include class inheritance

2025-08-29T21:54:43+00:00

While the original code came from the Sphinx Include class, such class is monolithic: it has only one function that does everything, and 3 variables that are used: - required_arguments - optional_arguments - option_spec So, basically those are the only members that remain from the original class, but hey! Those are the same vars that every other Sphinx directive extension has to define! In summary, keeping inheritance here doesn't make much sense. Worse than that, kernel-include doesn't support the current set of options that the original Include class has, but it also has its own set of options. So, let's fill in the argument vars with what it does support, dropping the rest. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/a9f2eebf11c6b0c3a2e3bf42e71392cdfd2835d1.1755872208.git.mchehab+huawei@kernel.org

docs: kernel_include.py: remove line numbers from parsed-literal

2025-08-29T21:54:43+00:00

When parsed-literal directive is added to rawtext, while cross references will be properly displayed, Sphinx will ignore line numbers. So, it is not worth adding them. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/b484fe5fcbf6e5217f112f205fbf54f0bbc3dcca.1755872208.git.mchehab+huawei@kernel.org

docs: kernel_include.py: move apply_range() and add a docstring

2025-08-29T21:54:43+00:00

While not required, better to have caller functions at the end. As apply_range() is now called by xref_text(), move it to be before the latter. No functional changes. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/a6ce0fd7c03a01338753fd81ed0c4631f78311d6.1755872208.git.mchehab+huawei@kernel.org

docs: kernel_include.py: append line numbers to better report errors

2025-08-29T21:54:43+00:00

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 Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/a0953af8b71e64aaf2e0ba4593ad39e19587d50a.1755872208.git.mchehab+huawei@kernel.org

docs: kernel_include.py: add support to generate a TOC table

2025-08-29T21:54:43+00:00

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 Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/c0d32cd1ef94017e05984b0a38bd2516f7db21e2.1755872208.git.mchehab+huawei@kernel.org

docs: kernel_include.py: move code and literal functions

2025-08-29T21:54:43+00:00

Simplify run() even more by moving the code which handles with code and literal blocks to their own functions. No functional changes. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/78d08dfa3f08adabc30bf93b8a1cde4e19b7bd41.1755872208.git.mchehab+huawei@kernel.org