Documentation/doc-guide/parse-headers.rst

Source file repositories/reference/linux-study-clean/Documentation/doc-guide/parse-headers.rst

File Facts

System
Linux kernel
Corpus path
Documentation/doc-guide/parse-headers.rst
Extension
.rst
Size
4956 bytes
Lines
188
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

===========================
Including uAPI header files
===========================

Sometimes, it is useful to include header files and C example codes in
order to describe the userspace API and to generate cross-references
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.

.. _parse_headers:

tools/docs/parse_headers.py
^^^^^^^^^^^^^^^^^^^^^^^^^^^

NAME
****

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

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
``FILE_RULES`` file to describe what elements will be either ignored or
be pointed to a non-default reference type/name.

The output is written at ``FILE_OUT``.

It is capable of identifying ``define``, ``struct``, ``typedef``, ``enum``
and enum ``symbol``, creating cross-references for all of them.

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

POSITIONAL ARGUMENTS
********************

  ``FILE_IN``
      Input C file

  ``FILE_OUT``
      Output RST file

  ``FILE_RULES``
      Exceptions file (optional)

OPTIONS
*******

  ``-h``, ``--help``

Annotation

Implementation Notes