Documentation/doc-guide/parse-headers.rst

2 Including uAPI header files
5 Sometimes, it is useful to include header files and C example codes in
6 order to describe the userspace API and to generate cross-references
7 between the code and the documentation. Adding cross-references for
10 uAPI documentation in sync with the Kernel changes.
12 cross-references. It has to be called via Makefile, while building the
13 documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example
24 parse_headers.py - parse a C file, in order to identify functions, structs,
25 enums and defines and create cross-references to a Sphinx book.
30 parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES``
35 Converts a C header or source file ``FILE_IN`` into a ReStructured Text
36 included via ..parsed-literal block with cross-references for the
39 be pointed to a non-default reference type/name.
44 and enum ``symbol``, creating cross-references for all of them.
47 Linux-specific macros used to define ``ioctl``.
70   ``-h``, ``--help``
72   ``-d``, ``--debug``
74   ``-t``, ``--toc``
81 Creates an enriched version of a Kernel header file with cross-links
83 reStructuredText notation, either as-is or as a table of contents.
86 either ignored or be pointed to a non-default reference, and optionally
90 uAPI headers will create cross-reference links to the code.
114     - A simple symbol name;
115     - A full Sphinx reference.
121     Sets C *namespace* to be used during cross-reference generation. Can
126     - ioctl:
129     - define:
132     - symbol:
135     - typedef:
138     - enum:
139         for the name of a non-anonymous enum;
141     - struct:
148 - Ignore a define ``_VIDEODEV2_H`` at ``FILE_IN``::
152 - On an data structure like this enum::
156   It won't generate cross-references for ``PRIVATE``::
167 - Use C namespace ``MC`` for all symbols at ``FILE_IN``::