From bb2e6adb4739eea65311677316fb40603fd5052c Mon Sep 17 00:00:00 2001 From: Karl Mehltretter Date: Sat, 5 Sep 2026 04:58:21 +0200 Subject: [PATCH] docs: parse-headers: Fix script name and stale Makefile reference The script is tools/docs/parse-headers.py, not parse_headers.py, and its FILE_RULES argument is optional. Commit 8a298579cdfc ("scripts: sphinx-build-wrapper: get rid of uapi/media Makefile") removed the Makefile the text points to as an example; the cross-references are now generated by the kernel-include directive, so point to a file that uses it. Fixes: d69a03a97a2d ("docs: doc-guide: parse-headers.rst update its documentation") Fixes: 8a298579cdfc ("scripts: sphinx-build-wrapper: get rid of uapi/media Makefile") Assisted-by: LLM Signed-off-by: Karl Mehltretter Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260905025821.83968-1-kmehltretter@gmail.com> --- Documentation/doc-guide/parse-headers.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst index a7bb01ff04eb..eb36c92e9a06 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/Documentation/doc-guide/parse-headers.rst @@ -8,26 +8,27 @@ between the code and the documentation. Adding cross-references for userspace API files has an additional advantage: Sphinx will generate warnings if a symbol is not found at the documentation. That helps to keep the uAPI documentation in sync with the Kernel changes. -The :ref:`parse_headers.py ` provides a way to generate such -cross-references. It has to be called via Makefile, while building the -documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example -about how to use it inside the Kernel tree. +The :ref:`parse-headers.py ` provides a way to generate such +cross-references. During the documentation build, the same parser is used by +the ``kernel-include`` directive with the ``:generate-cross-refs:`` option. +Please see ``Documentation/userspace-api/media/cec/cec-header.rst`` for an +example about how to use it inside the Kernel tree. .. _parse_headers: -tools/docs/parse_headers.py +tools/docs/parse-headers.py ^^^^^^^^^^^^^^^^^^^^^^^^^^^ NAME **** -parse_headers.py - parse a C file, in order to identify functions, structs, +parse-headers.py - parse a C file, in order to identify functions, structs, enums and defines and create cross-references to a Sphinx book. USAGE ***** -parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES`` +parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` [``FILE_RULES``] SYNOPSIS ********