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@xxxxxxxxxx/ 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
