Message-ID: <cover.1755784929.git.mchehab+huawei@kernel.org>
Date: Thu, 21 Aug 2025 16:21:06 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
	Jonathan Corbet <corbet@....net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	linux-kernel@...r.kernel.org,
	Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	Sean Young <sean@...s.org>,
	linux-media@...r.kernel.org
Subject: [PATCH 00/24] better handle media headers

Hi Jon,

Sorry for the big series. I wanted it to be smaller, by still this
is still only the first half of the history. I have a pile of other
patches on the top of this one to be sent - part of them to media.

This series comes after:
	https://lore.kernel.org/linux-doc/cover.1755258303.git.mchehab+huawei@kernel.org/

Its goal 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.

Mauro Carvalho Chehab (24):
  docs: parse-headers.pl: improve its debug output format
  docs: parse-headers.py: convert parse-headers.pl
  docs: parse-headers.py: improve --help logic
  docs: parse-headers.py: better handle @var arguments
  docs: parse-headers.py: simplify the rules for hashes
  tools: docs: parse-headers.py: move it from sphinx dir
  tools: docs: parse_data_structs.py: add methods to return output
  MAINTAINERS: add files from tools/docs to documentation entry
  docs: uapi: media: Makefile: use parse-headers.py
  docs: : Update its coding style
  docs: kernel_include.py: allow cross-reference generation
  docs: kernel_include.py: generate warnings for broken refs
  docs: kernel_include.py: move rawtext logic to separate functions
  docs: kernel_include.py: move range logic to a separate function
  docs: kernel_include.py: remove range restriction for gen docs
  docs: kernel_include.py: move code and literal functions
  docs: kernel_include.py: add support to generate a TOC table
  docs: kernel_include.py: append line numbers to better report errors
  docs: kernel_include.py: move apply_range() and add a docstring
  docs: kernel_include.py: remove line numbers from parsed-literal
  docs: kernel_include.py: remove Include class inheritance
  docs: kernel_include.py: document all supported parameters
  scripts: sphinx-build-wrapper: get rid of uapi/media Makefile
  docs: sphinx: drop parse-headers.pl

 .pylintrc                                     |   2 +-
 Documentation/sphinx/kernel_include.py        | 519 +++++++++++++-----
 Documentation/sphinx/parse-headers.pl         | 404 --------------
 Documentation/userspace-api/media/Makefile    |  64 ---
 .../userspace-api/media/cec/cec-header.rst    |   5 +-
 .../media/{ => cec}/cec.h.rst.exceptions      |   0
 .../media/{ => dvb}/ca.h.rst.exceptions       |   0
 .../media/{ => dvb}/dmx.h.rst.exceptions      |   0
 .../media/{ => dvb}/frontend.h.rst.exceptions |   0
 .../userspace-api/media/dvb/headers.rst       |  17 +-
 .../media/{ => dvb}/net.h.rst.exceptions      |   0
 .../media/mediactl/media-header.rst           |   5 +-
 .../{ => mediactl}/media.h.rst.exceptions     |   0
 .../userspace-api/media/rc/lirc-header.rst    |   4 +-
 .../media/{ => rc}/lirc.h.rst.exceptions      |   0
 .../userspace-api/media/v4l/videodev.rst      |   4 +-
 .../{ => v4l}/videodev2.h.rst.exceptions      |   0
 MAINTAINERS                                   |   1 +
 scripts/sphinx-build-wrapper                  |  48 --
 tools/docs/lib/__init__.py                    |   0
 tools/docs/lib/enrich_formatter.py            |  70 +++
 tools/docs/lib/parse_data_structs.py          | 452 +++++++++++++++
 tools/docs/parse-headers.py                   |  60 ++
 23 files changed, 984 insertions(+), 671 deletions(-)
 delete mode 100755 Documentation/sphinx/parse-headers.pl
 delete mode 100644 Documentation/userspace-api/media/Makefile
 rename Documentation/userspace-api/media/{ => cec}/cec.h.rst.exceptions (100%)
 rename Documentation/userspace-api/media/{ => dvb}/ca.h.rst.exceptions (100%)
 rename Documentation/userspace-api/media/{ => dvb}/dmx.h.rst.exceptions (100%)
 rename Documentation/userspace-api/media/{ => dvb}/frontend.h.rst.exceptions (100%)
 rename Documentation/userspace-api/media/{ => dvb}/net.h.rst.exceptions (100%)
 rename Documentation/userspace-api/media/{ => mediactl}/media.h.rst.exceptions (100%)
 rename Documentation/userspace-api/media/{ => rc}/lirc.h.rst.exceptions (100%)
 rename Documentation/userspace-api/media/{ => v4l}/videodev2.h.rst.exceptions (100%)
 create mode 100644 tools/docs/lib/__init__.py
 create mode 100644 tools/docs/lib/enrich_formatter.py
 create mode 100755 tools/docs/lib/parse_data_structs.py
 create mode 100755 tools/docs/parse-headers.py

-- 
2.50.1

Powered by blists - more mailing lists