[PATCH 00/23] Fix media uAPI cross references

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

In the past, media used Docbook to generate documentation, together
with some logic to ensure that cross-references would match the
actual defined uAPI.

The rationale is that we wanted to automatically check for uAPI
documentation gaps.

The same logic was migrated to Sphinx. Back then, broken links
were reported. However, recent versions of it and/or changes at
conf.py disabled such checks.

The result is that several symbols are now not cross-referenced,
and we don't get warnings anymore when something breaks.

This series consist on 2 parts:

Part 1: extra patches to parse_data_structs.py and kernel_include.py;
Part 2: media documentation fixes.

I'm not sure what's the best strategy to merge it, as some patches
belong to doc while others are media. So, they can be merged on
either one of the tree, or split on two series and merged in
separate or even being merged via a PR applied on both trees.

IMO, the latter is the better strategy.

Anyway, let's submit the series for review and discuss later about
its merge strategy.

Mauro Carvalho Chehab (23):
  tools: docs: parse_data_structs.py: drop contents header
  tools: docs: parse_data_structs.py: output a line number
  docs: kernel_include.py: fix line numbers for TOC
  docs: kernel_include.py: propose alternatives
  tools: docs: parse_data_structs: make process_exceptions two stages
  tools: docs: parse_data_structs.py: get rid of process_exceptions()
  tools: docs: parse_data_structs.py: add namespace support
  tools: docs: parse_data_structs.py: accept more reftypes
  docs: media: dvb: use TOC instead of file contents at headers
  docs: media: dvb: enable warnings for most headers
  docs: media: rc: use TOC instead of file contents for LIRC header
  docs: media: mediactl: use TOC instead of file contents
  docs: kernel_include.py: use get_close_matches() to propose
    alternatives
  docs: media: add missing c namespace to V4L headers
  docs: media: videodev2.h.rst.exceptions: fix namespace on refs
  media: docs: add a missing reference for VIDIOC_QUERY_CTRL
  media: docs: videodev2.h.rst.exceptions: ignore struct
    __kernel_v4l2_timeval
  media: docs: add some C domain missing references
  docs: cec: cec.h.rst.exceptions: fix broken references from cec.h
  docs: cec: show broken xrefs and show TOC instead of cec.h content
  docs: media: dmx_types: place kerneldoc at the right namespace
  docs: media: dvb: headers: warn about broken cross references
  docs: media: dvb: fix dmx.h.rst.exceptions

 Documentation/sphinx/kernel_include.py        | 110 ++++++-
 .../userspace-api/media/cec/cec-header.rst    |   8 +-
 .../media/cec/cec.h.rst.exceptions            |   3 +
 .../media/dvb/dmx.h.rst.exceptions            |  82 +++--
 .../userspace-api/media/dvb/dmx_types.rst     |   1 +
 .../media/dvb/frontend.h.rst.exceptions       |   5 +-
 .../userspace-api/media/dvb/headers.rst       |  31 +-
 .../media/mediactl/media-header.rst           |   8 +-
 .../media/mediactl/media.h.rst.exceptions     |   3 +
 .../userspace-api/media/rc/lirc-header.rst    |  14 +-
 .../userspace-api/media/v4l/app-pri.rst       |   1 +
 .../userspace-api/media/v4l/audio.rst         |   1 +
 .../userspace-api/media/v4l/biblio.rst        |   1 +
 .../userspace-api/media/v4l/buffer.rst        |   2 +
 .../media/v4l/capture-example.rst             |   1 +
 .../userspace-api/media/v4l/capture.c.rst     |   1 +
 .../media/v4l/colorspaces-defs.rst            |   1 +
 .../media/v4l/colorspaces-details.rst         |   1 +
 .../userspace-api/media/v4l/colorspaces.rst   |   1 +
 .../userspace-api/media/v4l/common-defs.rst   |   1 +
 .../userspace-api/media/v4l/common.rst        |   1 +
 .../userspace-api/media/v4l/compat.rst        |   1 +
 .../userspace-api/media/v4l/control.rst       |   1 +
 .../userspace-api/media/v4l/crop.rst          |   1 +
 .../userspace-api/media/v4l/depth-formats.rst |   1 +
 .../userspace-api/media/v4l/dev-decoder.rst   |   1 +
 .../userspace-api/media/v4l/dev-encoder.rst   |   1 +
 .../userspace-api/media/v4l/dev-event.rst     |   1 +
 .../userspace-api/media/v4l/dev-mem2mem.rst   |   1 +
 .../userspace-api/media/v4l/dev-meta.rst      |   1 +
 .../userspace-api/media/v4l/dev-osd.rst       |   1 +
 .../userspace-api/media/v4l/dev-overlay.rst   |   1 +
 .../userspace-api/media/v4l/dev-radio.rst     |   1 +
 .../userspace-api/media/v4l/dev-sdr.rst       |   1 +
 .../media/v4l/dev-stateless-decoder.rst       |   1 +
 .../userspace-api/media/v4l/dev-subdev.rst    |   1 +
 .../userspace-api/media/v4l/dev-touch.rst     |   1 +
 .../userspace-api/media/v4l/devices.rst       |   1 +
 .../userspace-api/media/v4l/dv-timings.rst    |   1 +
 .../media/v4l/ext-ctrls-camera.rst            |   1 +
 .../media/v4l/ext-ctrls-codec-stateless.rst   |   1 +
 .../media/v4l/ext-ctrls-codec.rst             |   1 +
 .../media/v4l/ext-ctrls-colorimetry.rst       |   1 +
 .../media/v4l/ext-ctrls-detect.rst            |   1 +
 .../userspace-api/media/v4l/ext-ctrls-dv.rst  |   1 +
 .../media/v4l/ext-ctrls-flash.rst             |   1 +
 .../media/v4l/ext-ctrls-fm-rx.rst             |   1 +
 .../media/v4l/ext-ctrls-fm-tx.rst             |   1 +
 .../media/v4l/ext-ctrls-image-process.rst     |   1 +
 .../media/v4l/ext-ctrls-image-source.rst      |   1 +
 .../media/v4l/ext-ctrls-jpeg.rst              |   1 +
 .../media/v4l/ext-ctrls-rf-tuner.rst          |   1 +
 .../media/v4l/extended-controls.rst           |   1 +
 .../userspace-api/media/v4l/field-order.rst   |   1 +
 .../userspace-api/media/v4l/fourcc.rst        |   1 +
 .../userspace-api/media/v4l/hsv-formats.rst   |   1 +
 .../userspace-api/media/v4l/libv4l.rst        |   1 +
 .../userspace-api/media/v4l/meta-formats.rst  |   1 +
 .../media/v4l/metafmt-c3-isp.rst              |   1 +
 .../userspace-api/media/v4l/metafmt-d4xx.rst  |   1 +
 .../media/v4l/metafmt-generic.rst             |   1 +
 .../media/v4l/metafmt-intel-ipu3.rst          |   1 +
 .../media/v4l/metafmt-pisp-be.rst             |   1 +
 .../media/v4l/metafmt-pisp-fe.rst             |   1 +
 .../media/v4l/metafmt-rkisp1.rst              |   1 +
 .../userspace-api/media/v4l/metafmt-uvc.rst   |   1 +
 .../userspace-api/media/v4l/metafmt-vivid.rst |   1 +
 .../media/v4l/metafmt-vsp1-hgo.rst            |   1 +
 .../media/v4l/metafmt-vsp1-hgt.rst            |   1 +
 .../userspace-api/media/v4l/pixfmt-bayer.rst  |   1 +
 .../userspace-api/media/v4l/pixfmt-cnf4.rst   |   1 +
 .../media/v4l/pixfmt-compressed.rst           |   1 +
 .../media/v4l/pixfmt-indexed.rst              |   1 +
 .../userspace-api/media/v4l/pixfmt-intro.rst  |   1 +
 .../userspace-api/media/v4l/pixfmt-inzi.rst   |   1 +
 .../userspace-api/media/v4l/pixfmt-m420.rst   |   1 +
 .../media/v4l/pixfmt-packed-hsv.rst           |   1 +
 .../media/v4l/pixfmt-packed-yuv.rst           |   1 +
 .../media/v4l/pixfmt-reserved.rst             |   1 +
 .../userspace-api/media/v4l/pixfmt-rgb.rst    |   1 +
 .../media/v4l/pixfmt-sdr-cs08.rst             |   1 +
 .../media/v4l/pixfmt-sdr-cs14le.rst           |   1 +
 .../media/v4l/pixfmt-sdr-cu08.rst             |   1 +
 .../media/v4l/pixfmt-sdr-cu16le.rst           |   1 +
 .../media/v4l/pixfmt-sdr-pcu16be.rst          |   1 +
 .../media/v4l/pixfmt-sdr-pcu18be.rst          |   1 +
 .../media/v4l/pixfmt-sdr-pcu20be.rst          |   1 +
 .../media/v4l/pixfmt-sdr-ru12le.rst           |   1 +
 .../media/v4l/pixfmt-srggb10-ipu3.rst         |   1 +
 .../media/v4l/pixfmt-srggb10.rst              |   1 +
 .../media/v4l/pixfmt-srggb10alaw8.rst         |   1 +
 .../media/v4l/pixfmt-srggb10dpcm8.rst         |   1 +
 .../media/v4l/pixfmt-srggb10p.rst             |   1 +
 .../media/v4l/pixfmt-srggb12.rst              |   1 +
 .../media/v4l/pixfmt-srggb12p.rst             |   1 +
 .../media/v4l/pixfmt-srggb14.rst              |   1 +
 .../media/v4l/pixfmt-srggb14p.rst             |   1 +
 .../media/v4l/pixfmt-srggb16.rst              |   1 +
 .../media/v4l/pixfmt-srggb8-pisp-comp.rst     |   1 +
 .../userspace-api/media/v4l/pixfmt-srggb8.rst |   1 +
 .../media/v4l/pixfmt-tch-td08.rst             |   1 +
 .../media/v4l/pixfmt-tch-td16.rst             |   1 +
 .../media/v4l/pixfmt-tch-tu08.rst             |   1 +
 .../media/v4l/pixfmt-tch-tu16.rst             |   1 +
 .../userspace-api/media/v4l/pixfmt-uv8.rst    |   1 +
 .../media/v4l/pixfmt-v4l2-mplane.rst          |   1 +
 .../userspace-api/media/v4l/pixfmt-v4l2.rst   |   1 +
 .../userspace-api/media/v4l/pixfmt-y12i.rst   |   1 +
 .../userspace-api/media/v4l/pixfmt-y16i.rst   |   1 +
 .../userspace-api/media/v4l/pixfmt-y8i.rst    |   1 +
 .../media/v4l/pixfmt-yuv-luma.rst             |   1 +
 .../media/v4l/pixfmt-yuv-planar.rst           |   1 +
 .../userspace-api/media/v4l/pixfmt-z16.rst    |   1 +
 .../userspace-api/media/v4l/pixfmt.rst        |   1 +
 .../userspace-api/media/v4l/planar-apis.rst   |   1 +
 .../userspace-api/media/v4l/querycap.rst      |   1 +
 .../userspace-api/media/v4l/sdr-formats.rst   |   1 +
 .../media/v4l/selection-api-configuration.rst |   1 +
 .../media/v4l/selection-api-examples.rst      |   1 +
 .../media/v4l/selection-api-intro.rst         |   1 +
 .../media/v4l/selection-api-targets.rst       |   1 +
 .../media/v4l/selection-api-vs-crop-api.rst   |   1 +
 .../userspace-api/media/v4l/selection-api.rst |   1 +
 .../media/v4l/selections-common.rst           |   1 +
 .../userspace-api/media/v4l/standard.rst      |   1 +
 .../media/v4l/subdev-formats.rst              |   1 +
 .../userspace-api/media/v4l/tch-formats.rst   |   1 +
 .../userspace-api/media/v4l/tuner.rst         |   1 +
 .../userspace-api/media/v4l/user-func.rst     |   1 +
 .../media/v4l/v4l2-selection-flags.rst        |   1 +
 .../media/v4l/v4l2-selection-targets.rst      |   1 +
 .../userspace-api/media/v4l/v4l2.rst          |   1 +
 .../media/v4l/v4l2grab-example.rst            |   1 +
 .../userspace-api/media/v4l/v4l2grab.c.rst    |   1 +
 .../userspace-api/media/v4l/video.rst         |   1 +
 .../userspace-api/media/v4l/videodev.rst      |   9 +-
 .../media/v4l/videodev2.h.rst.exceptions      | 288 +++++++++---------
 .../media/v4l/vidioc-queryctrl.rst            |   8 +
 .../userspace-api/media/v4l/yuv-formats.rst   |   1 +
 tools/docs/lib/parse_data_structs.py          | 230 ++++++++------
 tools/docs/parse-headers.py                   |   5 +-
 141 files changed, 608 insertions(+), 324 deletions(-)

-- 
2.51.0