[PATCH v2 00/24] better handle media headers

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Hi Jon,

Sorry for resending this big series. The content is almost identical
to the first version, but this one can be applied directly on the top
of docs/next, without requiring the sphinx-build-wrapper series.

I'm opting for this approach, in order to avoid adding 42 lines to
sphinx-build-wrapper just to be removed at the v1 of this series.

-

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.

-

v2:
   - makes it indepentent of sphinx-build-wrapper patch 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: kernel_include.py: 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/Makefile                        |   3 +-
 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                  | 719 ++++++++++++++++++
 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 ++
 24 files changed, 1704 insertions(+), 625 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 100755 scripts/sphinx-build-wrapper
 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