kernel/tools/docs/lib/parse_data_structs.py, branch 0x221E-v0.0-v7.0

docs: Move the python libraries to tools/lib/python

2025-11-18T16:22:40Z

"scripts/lib" was always a bit of an awkward place for Python modules. We already have tools/lib; create a tools/lib/python, move the libraries there, and update the users accordingly. While at it, move the contents of tools/docs/lib. Rather than make another directory, just put these documentation-oriented modules under "kdoc". Signed-off-by: Jonathan Corbet Message-ID: <20251110220430.726665-2-corbet@lwn.net>

tools: docs: parse_data_structs.py: accept more reftypes

2025-10-17T19:56:59Z

Current regex is limited to only some c-domain reftypes. There are several others. Change the code to pick the name specified there. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <5c146923d1e3183893f290216fb1378954e2e540.1759329363.git.mchehab+huawei@kernel.org>

tools: docs: parse_data_structs.py: add namespace support

2025-10-17T19:56:59Z

C domain supports a ".. c:namespace::" tag that allows setting a symbol namespace. This is used within the kernel to avoid warnings about duplicated symbols. This is specially important for syscalls, as each subsystem may have their own documentation for them. This is specially true for ioctl. When such tag is used, all C domain symbols have c++ style, e.g. they'll become "{namespace}.{reference}". Allow specifying C namespace at the exception files, avoiding the need of override rules for every symbol. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

tools: docs: parse_data_structs.py: get rid of process_exceptions()

2025-10-17T19:56:59Z

Add an extra parameter to parse_file to make it handle exceptions internally, cleaning up the API. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <8575bbc94ff706aa7e7cc3a188399ca17a3169e6.1759329363.git.mchehab+huawei@kernel.org>

tools: docs: parse_data_structs: make process_exceptions two stages

2025-10-17T19:56:59Z

Split the logic which parses exceptions on two stages, preparing the exceptions file to have rules that will affect xref generation. For now, preserve the original API. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

docs: kernel_include.py: fix line numbers for TOC

2025-10-17T19:56:59Z

On TOC output, we need to embeed line numbers with ViewList. Change the parse class to produce a line-number parsed result, and adjust the output accordingly. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <74eed96e32f79eaaef7a99ffe7c3224fed369c27.1759329363.git.mchehab+huawei@kernel.org>

tools: docs: parse_data_structs.py: output a line number

2025-10-17T19:56:59Z

Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

tools: docs: parse_data_structs.py: drop contents header

2025-10-17T19:56:59Z

When used in practice, one may want to have multiple header files on a single rst file, like: *********************** Digital TV uAPI symbols *********************** .. contents:: Table of Contents :depth: 2 :local: Frontend ======== .. kernel-include:: include/uapi/linux/dvb/frontend.h :generate-cross-refs: :toc: Demux ===== .. kernel-include:: include/uapi/linux/dvb/dmx.h :generate-cross-refs: :toc: ... So, don't add ..contents:: here. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <4bf353e5248133a3b0abd82519a38453402fe7c6.1759329363.git.mchehab+huawei@kernel.org>

tools: docs: parse_data_structs.py: add methods to return output

2025-08-29T21:54:42Z

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

tools: docs: parse-headers.py: move it from sphinx dir

2025-08-29T21:54:42Z

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