From: Jonathan Corbet <corbet@lwn.net>
Date: Fri, 29 Aug 2025 21:58:48 +0000 (-0600)
Subject: Merge branch 'mauro' into docs-mw
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=c67a9f492c3c15ef1695c629bf5cc57f674a8e83;p=thirdparty%2Fkernel%2Fstable.git

Merge branch 'mauro' into docs-mw

Another build series from Mauro:

The goal of this series is to drop one of the most ancient and ugliest
hack from the documentation build system. Before migrating to Sphinx,
the media subsystem already had a very comprehensive uAPI book, together
with a build time system to detect and point for any documentation gaps.

When migrating to Sphinx, we ported the logic to a Perl script
(parse-headers.pl) and Markus came up with a Sphinx extension
(kernel_include.py). We also added some files to control how parse-headers
produce results, and a Makefile.

At the initial Sphinx versions (1.4.1 if I recall correctly), when
a new symbol is added to videodev2.h, a new warning were
produced at documentatiion time, it the patchset didn't have
the corresponding documentation path.

While kernel-include is generic, the only user at the moment is the media
subsystem.

This series gets rid of the Python script, replacing it by a command
line script and a class. The parse header class can optionally be used by
kernel-include to produce an enriched code that will contain cross-references.

As the other conversions, it starts with a bug-compatible version of
parse-headers, but the subsequent patches add more functionalities and
fix bugs.

It should be noticed that modern of Sphinx disabled the cross-reference
warnings. So, at the next series, I'll be re-adding it in a controlled way
(e.g. just for the references from kernel-include that has an special
argument).

The script also supports now generating a "toc" output, which will be used
at the next series.
---

c67a9f492c3c15ef1695c629bf5cc57f674a8e83