[PATCH] docs: parse-headers: Fix script name and stale Makefile reference

[PATCH] docs: parse-headers: Fix script name and stale Makefile reference

[Karl Mehltretter]

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 <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 <parse_headers>` 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 <parse_headers>` 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
 ********
-- 
2.53.0

Re: [PATCH] docs: parse-headers: Fix script name and stale Makefile reference

[Randy Dunlap]

On 9/4/26 7:58 PM, Karl Mehltretter wrote:
> 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 <kmehltretter@gmail.com>

Acked-by: Randy Dunlap <rdunlap@infradead.org>

I would like to see documentation for kernel-include added to
Documentation/doc-guide/kernel-doc.rst or doc-guide/parse-headers.rst.
I'm surprised that it's there already.

Thanks.

> ---
>  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 <parse_headers>` 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 <parse_headers>` 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
>  ********

-- 
~Randy

Re: [PATCH] docs: parse-headers: Fix script name and stale Makefile reference

[Jonathan Corbet]

Karl Mehltretter <kmehltretter@gmail.com> writes:

> 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 <kmehltretter@gmail.com>
> ---
>  Documentation/doc-guide/parse-headers.rst | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)

Applied, thanks.

jon