From: Mauro Carvalho Chehab Date: Sat, 8 Nov 2025 09:37:04 +0000 (+0100) Subject: docs: doc-guide: parse-headers.rst update its documentation X-Git-Url: https://gentwo.org/gitweb/?a=commitdiff_plain;h=d69a03a97a2d9a85d344b5988640d7f5cf6f598b;p=linux%2F.git docs: doc-guide: parse-headers.rst update its documentation Besides converting from Perl to Python, parse-headers has gained some new functionality and was moved to tools/docs. Update its documentation accordingly. Reported-by: Randy Dunlap Closes: https://lore.kernel.org/linux-doc/9391a0f0-7c92-42aa-8190-28255b22e131@infradead.org/ Acked-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Dongliang Mu Signed-off-by: Jonathan Corbet Message-ID: <1f9025dc98dc58da3cc31f3343d5027f351be338.1762594622.git.mchehab+huawei@kernel.org> --- diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst index 204b025f1349..954f3285ddf6 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/Documentation/doc-guide/parse-headers.rst @@ -8,170 +8,165 @@ between the code and the documentation. Adding cross-references for userspace API files has an additional vantage: 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.pl ` provide a way to generate such +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. .. _parse_headers: -parse_headers.pl -^^^^^^^^^^^^^^^^ +tools/docs/parse_headers.py +^^^^^^^^^^^^^^^^^^^^^^^^^^^ NAME **** - -parse_headers.pl - 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`` SYNOPSIS ******** - -\ **parse_headers.pl**\ [] [] - -Where can be: --debug, --help or --usage. - - -OPTIONS -******* - - - -\ **--debug**\ - - Put the script in verbose mode, useful for debugging. - - - -\ **--usage**\ - - Prints a brief help message and exits. - - - -\ **--help**\ - - Prints a more detailed help message and exits. - - -DESCRIPTION -*********** - - -Convert a C header or source file (C_FILE), into a reStructuredText +Converts a C header or source file ``FILE_IN`` into a ReStructured Text included via ..parsed-literal block with cross-references for the documentation files that describe the API. It accepts an optional -EXCEPTIONS_FILE with describes what elements will be either ignored or -be pointed to a non-default reference. - -The output is written at the (OUT_FILE). +``FILE_RULES`` file to describe what elements will be either ignored or +be pointed to a non-default reference type/name. -It is capable of identifying defines, functions, structs, typedefs, -enums and enum symbols and create cross-references for all of them. -It is also capable of distinguish #define used for specifying a Linux -ioctl. +The output is written at ``FILE_OUT``. -The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ **replace**\ . +It is capable of identifying ``define``, ``struct``, ``typedef``, ``enum`` +and enum ``symbol``, creating cross-references for all of them. -The syntax for the ignore tag is: +It is also capable of distinguishing ``#define`` used for specifying +Linux-specific macros used to define ``ioctl``. +The optional ``FILE_RULES`` contains a set of rules like:: -ignore \ **type**\ \ **name**\ + ignore ioctl VIDIOC_ENUM_FMT + replace ioctl VIDIOC_DQBUF vidioc_qbuf + replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det` -The \ **ignore**\ means that it won't generate cross references for a -\ **name**\ symbol of type \ **type**\ . +POSITIONAL ARGUMENTS +******************** -The syntax for the replace tag is: + ``FILE_IN`` + Input C file + ``FILE_OUT`` + Output RST file -replace \ **type**\ \ **name**\ \ **new_value**\ + ``FILE_RULES`` + Exceptions file (optional) -The \ **replace**\ means that it will generate cross references for a -\ **name**\ symbol of type \ **type**\ , but, instead of using the default -replacement rule, it will use \ **new_value**\ . - -For both statements, \ **type**\ can be either one of the following: +OPTIONS +******* + ``-h``, ``--help`` + show a help message and exit + ``-d``, ``--debug`` + Increase debug level. Can be used multiple times + ``-t``, ``--toc`` + instead of a literal block, outputs a TOC table at the RST file -\ **ioctl**\ - The ignore or replace statement will apply to ioctl definitions like: +DESCRIPTION +*********** - #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) +Creates an enriched version of a Kernel header file with cross-links +to each C data structure type, from ``FILE_IN``, formatting it with +reStructuredText notation, either as-is or as a table of contents. +It accepts an optional ``FILE_RULES`` which describes what elements will be +either ignored or be pointed to a non-default reference, and optionally +defines the C namespace to be used. +It is meant to allow having more comprehensive documentation, where +uAPI headers will create cross-reference links to the code. -\ **define**\ +The output is written at the (``FILE_OUT``). - The ignore or replace statement will apply to any other #define found - at C_FILE. +The ``FILE_RULES`` may contain contain three types of statements: +**ignore**, **replace** and **namespace**. +By default, it create rules for all symbols and defines, but it also +allows parsing an exception file. Such file contains a set of rules +using the syntax below: +1. Ignore rules: -\ **typedef**\ + ignore *type* *symbol* - The ignore or replace statement will apply to typedef statements at C_FILE. +Removes the symbol from reference generation. +2. Replace rules: + replace *type* *old_symbol* *new_reference* -\ **struct**\ + Replaces *old_symbol* with a *new_reference*. + The *new_reference* can be: - The ignore or replace statement will apply to the name of struct statements - at C_FILE. + - A simple symbol name; + - A full Sphinx reference. +3. Namespace rules + namespace *namespace* -\ **enum**\ + Sets C *namespace* to be used during cross-reference generation. Can + be overridden by replace rules. - The ignore or replace statement will apply to the name of enum statements - at C_FILE. +On ignore and replace rules, *type* can be: + - ioctl: + for defines of the form ``_IO*``, e.g., ioctl definitions + - define: + for other defines -\ **symbol**\ + - symbol: + for symbols defined within enums; - The ignore or replace statement will apply to the name of enum value - at C_FILE. + - typedef: + for typedefs; - For replace statements, \ **new_value**\ will automatically use :c:type: - references for \ **typedef**\ , \ **enum**\ and \ **struct**\ types. It will use :ref: - for \ **ioctl**\ , \ **define**\ and \ **symbol**\ types. The type of reference can - also be explicitly defined at the replace statement. + - enum: + for the name of a non-anonymous enum; + - struct: + for structs. EXAMPLES ******** +- Ignore a define ``_VIDEODEV2_H`` at ``FILE_IN``:: -ignore define _VIDEODEV2_H - - -Ignore a #define _VIDEODEV2_H at the C_FILE. - -ignore symbol PRIVATE - + ignore define _VIDEODEV2_H -On a struct like: +- On an data structure like this enum:: -enum foo { BAR1, BAR2, PRIVATE }; + enum foo { BAR1, BAR2, PRIVATE }; -It won't generate cross-references for \ **PRIVATE**\ . + It won't generate cross-references for ``PRIVATE``:: -replace symbol BAR1 :c:type:\`foo\` -replace symbol BAR2 :c:type:\`foo\` + ignore symbol PRIVATE + At the same struct, instead of creating one cross reference per symbol, + make them all point to the ``enum foo`` C type:: -On a struct like: + replace symbol BAR1 :c:type:\`foo\` + replace symbol BAR2 :c:type:\`foo\` -enum foo { BAR1, BAR2, PRIVATE }; -It will make the BAR1 and BAR2 enum symbols to cross reference the foo -symbol at the C domain. +- Use C namespace ``MC`` for all symbols at ``FILE_IN``:: + namespace MC BUGS **** @@ -184,7 +179,7 @@ COPYRIGHT ********* -Copyright (c) 2016 by Mauro Carvalho Chehab . +Copyright (c) 2016, 2025 by Mauro Carvalho Chehab . License GPLv2: GNU GPL version 2 . diff --git a/Documentation/translations/it_IT/doc-guide/parse-headers.rst b/Documentation/translations/it_IT/doc-guide/parse-headers.rst index 026a23e49767..b0caa40fe1e9 100644 --- a/Documentation/translations/it_IT/doc-guide/parse-headers.rst +++ b/Documentation/translations/it_IT/doc-guide/parse-headers.rst @@ -13,28 +13,28 @@ dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi d'avviso se un simbolo non viene trovato nella documentazione. Questo permette di mantenere allineate la documentazione della uAPI (API spazio utente) con le modifiche del kernel. -Il programma :ref:`parse_headers.pl ` genera questi riferimenti. +Il programma :ref:`parse_headers.py ` genera questi riferimenti. Esso dev'essere invocato attraverso un Makefile, mentre si genera la documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel consultate ``Documentation/userspace-api/media/Makefile``. .. _it_parse_headers: -parse_headers.pl +parse_headers.py ^^^^^^^^^^^^^^^^ NOME **** -parse_headers.pl - analizza i file C al fine di identificare funzioni, +parse_headers.py - analizza i file C al fine di identificare funzioni, strutture, enumerati e definizioni, e creare riferimenti per Sphinx SINTASSI ******** -\ **parse_headers.pl**\ [] [] +\ **parse_headers.py**\ [] [] Dove può essere: --debug, --usage o --help. diff --git a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst index a08819e904ed..65d9dc5143ff 100644 --- a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst +++ b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst @@ -13,20 +13,20 @@ 有时，为了描述用户空间API并在代码和文档之间生成交叉引用，需要包含头文件和示例 C代码。为用户空间API文件添加交叉引用还有一个好处：如果在文档中找不到相应符号， Sphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。 -:ref:`parse_headers.pl ` 提供了生成此类交叉引用的一种方法。 +:ref:`parse_headers.py ` 提供了生成此类交叉引用的一种方法。 在构建文档时，必须通过Makefile调用它。有关如何在内核树中使用它的示例，请参阅 ``Documentation/userspace-api/media/Makefile`` 。 .. _parse_headers_zh: -parse_headers.pl +parse_headers.py ---------------- 脚本名称 ~~~~~~~~ -parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档 +parse_headers.py——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档 创建交叉引用。 @@ -34,7 +34,7 @@ parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、 ~~~~~~~~ -\ **parse_headers.pl**\ [<选项>] <输出文件> [<例外文件>] +\ **parse_headers.py**\ [<选项>] <输出文件> [<例外文件>] <选项> 可以是： --debug, --help 或 --usage 。