[PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+

linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed

* [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+
@ 2020-09-25  6:30 Mauro Carvalho Chehab
  2020-09-25  6:30 ` [PATCH v3 1/8] docs: cdomain.py: add support for a new Sphinx 3.1+ tag Mauro Carvalho Chehab
                   ` (6 more replies)
  0 siblings, 7 replies; 9+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-25  6:30 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
	Niklas Söderlund, Alexandre Courbot, Arnd Bergmann,
	Boris Brezillon, Ezequiel Garcia, Hans Verkuil, Helen Koike,
	Jacopo Mondi, Jernej Skrabec, Jian-Jia Su, Laurent Pinchart,
	Mauro Carvalho Chehab, Michael Tretter, Paul Kocialkowski,
	Philipp Zabel, Randy Dunlap, Ricardo Ribalda, Sakari Ailus,
	Sean Young, Sergey Senozhatsky, Tomasz Figa, linux-media

Sphinx 3.x new c domain code broke the doc build on several ways:

- it broke the cdomains.py extension that were giving namespace
  support for C references;
- it broke the automarkup script;
- it broke c:type references that kernel-doc and other parts of the
  kernel were using to do cross-references with C declarations.

This series address only part of those issues. It halves the number
of warnings produced when Spinx 3.x is used.  Yet, we still
have 1.7 K warnings.

The good thing is that the media documentation is almost
clean of warnings (there are still some warnings at the glossary,
that are unrelated to C domains). 

At this version 3, I changed the first patch to only support
Sphinx 3.1+ namespaces. This is enough for fixing the issues
at the media docs. 

The second patch disables the automarkup extension on
Sphinx 3.x. Due to the C domain code re-write, the internal
representation of C references is different. It sounds that
the x-ref class needs to be "cexpr" or something like that,
but futher work is required. So, for now, let's just disable it.

Patch 3 makes kernel-doc aware of Sphinx version, and makes
it use a different syntax for Sphinx 3.x. I'm not sure if all
cases were covered there, but at least the most common
one (wrong usage of c:type reference) was covered.

The remaining patches change the media documentation
for it to use the c:namespace macro.

Mauro Carvalho Chehab (8):
  docs: cdomain.py: add support for a new Sphinx 3.1+ tag
  docs: conf.py: disable automarkup for Sphinx 3.x
  scripts: kernel-doc: make it more compatible with Sphinx 3.x
  media: docs: make CEC documents compatible with Sphinx 3.1+
  media: docs: make V4L documents more compatible with Sphinx 3.1+
  media: docs: make DVB documents more compatible with Sphinx 3.1+
  media: docs: make MC documents more compatible with Sphinx 3.1+
  media: docs: make RC documents more compatible with Sphinx 3.1+

 Documentation/conf.py                         |  4 +-
 Documentation/sphinx/cdomain.py               | 55 +++++++++++++-
 .../media/cec/cec-func-close.rst              | 10 +--
 .../media/cec/cec-func-ioctl.rst              | 11 +--
 .../userspace-api/media/cec/cec-func-open.rst | 10 +--
 .../userspace-api/media/cec/cec-func-poll.rst | 14 ++--
 .../media/cec/cec-ioc-adap-g-caps.rst         | 10 +--
 .../media/cec/cec-ioc-adap-g-conn-info.rst    | 11 +--
 .../media/cec/cec-ioc-adap-g-log-addrs.rst    | 20 ++---
 .../media/cec/cec-ioc-adap-g-phys-addr.rst    | 15 ++--
 .../media/cec/cec-ioc-dqevent.rst             | 15 ++--
 .../media/cec/cec-ioc-g-mode.rst              | 16 ++--
 .../media/cec/cec-ioc-receive.rst             | 18 ++---
 .../dvb/audio-bilingual-channel-select.rst    |  7 +-
 .../media/dvb/audio-channel-select.rst        |  8 +-
 .../media/dvb/audio-clear-buffer.rst          |  8 +-
 .../media/dvb/audio-continue.rst              |  7 +-
 .../userspace-api/media/dvb/audio-fclose.rst  |  7 +-
 .../userspace-api/media/dvb/audio-fopen.rst   |  7 +-
 .../userspace-api/media/dvb/audio-fwrite.rst  |  7 +-
 .../media/dvb/audio-get-capabilities.rst      |  8 +-
 .../media/dvb/audio-get-status.rst            |  8 +-
 .../userspace-api/media/dvb/audio-pause.rst   |  9 +--
 .../userspace-api/media/dvb/audio-play.rst    |  7 +-
 .../media/dvb/audio-select-source.rst         |  8 +-
 .../media/dvb/audio-set-av-sync.rst           |  8 +-
 .../media/dvb/audio-set-bypass-mode.rst       |  9 +--
 .../userspace-api/media/dvb/audio-set-id.rst  |  9 +--
 .../media/dvb/audio-set-mixer.rst             |  9 +--
 .../media/dvb/audio-set-mute.rst              |  8 +-
 .../media/dvb/audio-set-streamtype.rst        | 10 +--
 .../userspace-api/media/dvb/audio-stop.rst    |  9 +--
 .../userspace-api/media/dvb/ca-fclose.rst     |  7 +-
 .../userspace-api/media/dvb/ca-fopen.rst      |  7 +-
 .../userspace-api/media/dvb/ca-get-cap.rst    |  8 +-
 .../media/dvb/ca-get-descr-info.rst           |  9 ++-
 .../userspace-api/media/dvb/ca-get-msg.rst    | 10 +--
 .../media/dvb/ca-get-slot-info.rst            |  9 +--
 .../userspace-api/media/dvb/ca-reset.rst      |  9 +--
 .../userspace-api/media/dvb/ca-send-msg.rst   |  9 +--
 .../userspace-api/media/dvb/ca-set-descr.rst  |  8 +-
 .../userspace-api/media/dvb/dmx-add-pid.rst   | 10 +--
 .../userspace-api/media/dvb/dmx-expbuf.rst    | 11 +--
 .../userspace-api/media/dvb/dmx-fclose.rst    |  9 +--
 .../userspace-api/media/dvb/dmx-fopen.rst     |  5 +-
 .../userspace-api/media/dvb/dmx-fread.rst     |  7 +-
 .../userspace-api/media/dvb/dmx-fwrite.rst    |  6 +-
 .../media/dvb/dmx-get-pes-pids.rst            | 12 ++-
 .../userspace-api/media/dvb/dmx-get-stc.rst   | 12 ++-
 .../userspace-api/media/dvb/dmx-mmap.rst      | 15 ++--
 .../userspace-api/media/dvb/dmx-munmap.rst    | 14 ++--
 .../userspace-api/media/dvb/dmx-qbuf.rst      | 17 ++---
 .../userspace-api/media/dvb/dmx-querybuf.rst  |  9 +--
 .../media/dvb/dmx-remove-pid.rst              | 10 +--
 .../userspace-api/media/dvb/dmx-reqbufs.rst   |  9 +--
 .../media/dvb/dmx-set-buffer-size.rst         | 10 +--
 .../media/dvb/dmx-set-filter.rst              | 12 ++-
 .../media/dvb/dmx-set-pes-filter.rst          | 13 +---
 .../userspace-api/media/dvb/dmx-start.rst     | 11 +--
 .../userspace-api/media/dvb/dmx-stop.rst      |  9 +--
 .../media/dvb/fe-diseqc-recv-slave-reply.rst  |  9 +--
 .../media/dvb/fe-diseqc-reset-overload.rst    |  9 +--
 .../media/dvb/fe-diseqc-send-burst.rst        | 10 +--
 .../media/dvb/fe-diseqc-send-master-cmd.rst   |  9 +--
 .../dvb/fe-dishnetwork-send-legacy-cmd.rst    | 10 +--
 .../media/dvb/fe-enable-high-lnb-voltage.rst  | 10 +--
 .../userspace-api/media/dvb/fe-get-event.rst  | 12 +--
 .../media/dvb/fe-get-frontend.rst             | 12 +--
 .../userspace-api/media/dvb/fe-get-info.rst   | 11 +--
 .../media/dvb/fe-get-property.rst             | 15 ++--
 .../userspace-api/media/dvb/fe-read-ber.rst   |  9 +--
 .../media/dvb/fe-read-signal-strength.rst     |  9 +--
 .../userspace-api/media/dvb/fe-read-snr.rst   |  9 +--
 .../media/dvb/fe-read-status.rst              | 11 +--
 .../media/dvb/fe-read-uncorrected-blocks.rst  |  9 +--
 .../media/dvb/fe-set-frontend-tune-mode.rst   | 10 +--
 .../media/dvb/fe-set-frontend.rst             | 11 +--
 .../userspace-api/media/dvb/fe-set-tone.rst   | 10 +--
 .../media/dvb/fe-set-voltage.rst              | 10 +--
 .../media/dvb/frontend_f_close.rst            |  8 +-
 .../media/dvb/frontend_f_open.rst             | 10 +--
 .../userspace-api/media/dvb/net-add-if.rst    |  9 +--
 .../userspace-api/media/dvb/net-get-if.rst    | 10 +--
 .../userspace-api/media/dvb/net-remove-if.rst | 10 +--
 .../media/dvb/video-clear-buffer.rst          |  8 +-
 .../userspace-api/media/dvb/video-command.rst | 10 +--
 .../media/dvb/video-continue.rst              |  8 +-
 .../media/dvb/video-fast-forward.rst          | 10 +--
 .../userspace-api/media/dvb/video-fclose.rst  |  6 +-
 .../userspace-api/media/dvb/video-fopen.rst   |  6 +-
 .../userspace-api/media/dvb/video-freeze.rst  |  8 +-
 .../userspace-api/media/dvb/video-fwrite.rst  |  6 +-
 .../media/dvb/video-get-capabilities.rst      |  8 +-
 .../media/dvb/video-get-event.rst             |  8 +-
 .../media/dvb/video-get-frame-count.rst       |  8 +-
 .../userspace-api/media/dvb/video-get-pts.rst |  8 +-
 .../media/dvb/video-get-size.rst              |  8 +-
 .../media/dvb/video-get-status.rst            |  7 +-
 .../userspace-api/media/dvb/video-play.rst    |  8 +-
 .../media/dvb/video-select-source.rst         |  7 +-
 .../media/dvb/video-set-blank.rst             |  8 +-
 .../media/dvb/video-set-display-format.rst    |  8 +-
 .../media/dvb/video-set-format.rst            |  9 +--
 .../media/dvb/video-set-streamtype.rst        |  8 +-
 .../media/dvb/video-slowmotion.rst            | 10 +--
 .../media/dvb/video-stillpicture.rst          |  8 +-
 .../userspace-api/media/dvb/video-stop.rst    |  8 +-
 .../media/dvb/video-try-command.rst           |  8 +-
 .../media/mediactl/media-func-close.rst       | 10 +--
 .../media/mediactl/media-func-ioctl.rst       | 10 +--
 .../media/mediactl/media-func-open.rst        | 10 +--
 .../media/mediactl/media-ioc-device-info.rst  | 13 +---
 .../mediactl/media-ioc-enum-entities.rst      | 11 +--
 .../media/mediactl/media-ioc-enum-links.rst   | 13 +---
 .../media/mediactl/media-ioc-g-topology.rst   | 14 +---
 .../mediactl/media-ioc-request-alloc.rst      | 11 ++-
 .../media/mediactl/media-ioc-setup-link.rst   | 10 +--
 .../mediactl/media-request-ioc-queue.rst      |  7 +-
 .../mediactl/media-request-ioc-reinit.rst     |  8 +-
 .../media/mediactl/request-api.rst            |  5 +-
 .../media/mediactl/request-func-close.rst     |  8 +-
 .../media/mediactl/request-func-ioctl.rst     |  8 +-
 .../media/mediactl/request-func-poll.rst      | 12 +--
 .../media/rc/lirc-get-features.rst            |  9 +--
 .../media/rc/lirc-get-rec-mode.rst            | 12 +--
 .../media/rc/lirc-get-rec-resolution.rst      |  8 +-
 .../media/rc/lirc-get-send-mode.rst           | 14 ++--
 .../media/rc/lirc-get-timeout.rst             | 13 ++--
 .../userspace-api/media/rc/lirc-read.rst      | 10 +--
 .../rc/lirc-set-measure-carrier-mode.rst      |  8 +-
 .../media/rc/lirc-set-rec-carrier-range.rst   |  6 +-
 .../media/rc/lirc-set-rec-carrier.rst         |  8 +-
 .../media/rc/lirc-set-rec-timeout-reports.rst |  8 +-
 .../media/rc/lirc-set-rec-timeout.rst         | 13 ++--
 .../media/rc/lirc-set-send-carrier.rst        |  8 +-
 .../media/rc/lirc-set-send-duty-cycle.rst     |  8 +-
 .../media/rc/lirc-set-transmitter-mask.rst    |  8 +-
 .../media/rc/lirc-set-wideband-receiver.rst   |  8 +-
 .../userspace-api/media/rc/lirc-write.rst     |  7 +-
 .../userspace-api/media/v4l/buffer.rst        | 14 +---
 .../userspace-api/media/v4l/dev-capture.rst   |  7 +-
 .../userspace-api/media/v4l/dev-output.rst    |  7 +-
 .../userspace-api/media/v4l/dev-raw-vbi.rst   | 19 ++---
 .../userspace-api/media/v4l/dev-rds.rst       | 12 +--
 .../media/v4l/dev-sliced-vbi.rst              | 31 ++------
 .../userspace-api/media/v4l/diff-v4l.rst      | 39 ++--------
 .../userspace-api/media/v4l/dmabuf.rst        |  8 +-
 .../userspace-api/media/v4l/format.rst        |  7 +-
 .../userspace-api/media/v4l/func-close.rst    |  8 +-
 .../userspace-api/media/v4l/func-ioctl.rst    | 10 +--
 .../userspace-api/media/v4l/func-mmap.rst     | 18 ++---
 .../userspace-api/media/v4l/func-munmap.rst   | 14 ++--
 .../userspace-api/media/v4l/func-open.rst     | 14 ++--
 .../userspace-api/media/v4l/func-poll.rst     | 40 +++++-----
 .../userspace-api/media/v4l/func-read.rst     | 39 +++++-----
 .../userspace-api/media/v4l/func-select.rst   | 42 +++++-----
 .../userspace-api/media/v4l/func-write.rst    | 13 ++--
 .../userspace-api/media/v4l/hist-v4l2.rst     | 76 +------------------
 Documentation/userspace-api/media/v4l/io.rst  |  6 +-
 .../media/v4l/libv4l-introduction.rst         | 30 ++++----
 .../userspace-api/media/v4l/mmap.rst          | 26 +++----
 .../userspace-api/media/v4l/open.rst          | 15 ++--
 Documentation/userspace-api/media/v4l/rw.rst  | 18 ++---
 .../userspace-api/media/v4l/streaming-par.rst |  5 +-
 .../userspace-api/media/v4l/userp.rst         | 11 +--
 .../media/v4l/vidioc-create-bufs.rst          | 11 +--
 .../media/v4l/vidioc-cropcap.rst              | 11 +--
 .../media/v4l/vidioc-dbg-g-chip-info.rst      | 13 +---
 .../media/v4l/vidioc-dbg-g-register.rst       | 18 ++---
 .../media/v4l/vidioc-decoder-cmd.rst          | 19 ++---
 .../media/v4l/vidioc-dqevent.rst              | 19 +----
 .../media/v4l/vidioc-dv-timings-cap.rst       | 17 ++---
 .../media/v4l/vidioc-encoder-cmd.rst          | 25 +++---
 .../media/v4l/vidioc-enum-dv-timings.rst      | 16 ++--
 .../media/v4l/vidioc-enum-fmt.rst             | 12 +--
 .../media/v4l/vidioc-enum-frameintervals.rst  | 15 +---
 .../media/v4l/vidioc-enum-framesizes.rst      | 16 +---
 .../media/v4l/vidioc-enum-freq-bands.rst      | 12 +--
 .../media/v4l/vidioc-enumaudio.rst            | 10 +--
 .../media/v4l/vidioc-enumaudioout.rst         | 10 +--
 .../media/v4l/vidioc-enuminput.rst            | 14 +---
 .../media/v4l/vidioc-enumoutput.rst           | 13 +---
 .../media/v4l/vidioc-enumstd.rst              | 23 ++----
 .../userspace-api/media/v4l/vidioc-expbuf.rst | 14 +---
 .../media/v4l/vidioc-g-audio.rst              | 18 ++---
 .../media/v4l/vidioc-g-audioout.rst           | 16 ++--
 .../userspace-api/media/v4l/vidioc-g-crop.rst | 16 ++--
 .../userspace-api/media/v4l/vidioc-g-ctrl.rst | 16 ++--
 .../media/v4l/vidioc-g-dv-timings.rst         | 26 +++----
 .../userspace-api/media/v4l/vidioc-g-edid.rst | 25 +++---
 .../media/v4l/vidioc-g-enc-index.rst          | 13 +---
 .../media/v4l/vidioc-g-ext-ctrls.rst          | 21 ++---
 .../userspace-api/media/v4l/vidioc-g-fbuf.rst | 18 ++---
 .../userspace-api/media/v4l/vidioc-g-fmt.rst  | 22 +++---
 .../media/v4l/vidioc-g-frequency.rst          | 16 ++--
 .../media/v4l/vidioc-g-input.rst              | 15 ++--
 .../media/v4l/vidioc-g-jpegcomp.rst           | 17 ++---
 .../media/v4l/vidioc-g-modulator.rst          | 17 ++---
 .../media/v4l/vidioc-g-output.rst             | 15 ++--
 .../userspace-api/media/v4l/vidioc-g-parm.rst | 30 +++-----
 .../media/v4l/vidioc-g-priority.rst           | 16 ++--
 .../media/v4l/vidioc-g-selection.rst          | 15 ++--
 .../media/v4l/vidioc-g-sliced-vbi-cap.rst     | 12 +--
 .../userspace-api/media/v4l/vidioc-g-std.rst  | 24 +++---
 .../media/v4l/vidioc-g-tuner.rst              | 19 ++---
 .../media/v4l/vidioc-log-status.rst           | 10 +--
 .../media/v4l/vidioc-overlay.rst              | 10 +--
 .../media/v4l/vidioc-prepare-buf.rst          | 10 +--
 .../userspace-api/media/v4l/vidioc-qbuf.rst   | 17 ++---
 .../media/v4l/vidioc-query-dv-timings.rst     | 15 ++--
 .../media/v4l/vidioc-querybuf.rst             | 10 +--
 .../media/v4l/vidioc-querycap.rst             | 16 ++--
 .../media/v4l/vidioc-queryctrl.rst            | 22 ++----
 .../media/v4l/vidioc-querystd.rst             | 15 ++--
 .../media/v4l/vidioc-reqbufs.rst              | 10 +--
 .../media/v4l/vidioc-s-hw-freq-seek.rst       | 11 +--
 .../media/v4l/vidioc-streamon.rst             | 14 ++--
 .../v4l/vidioc-subdev-enum-frame-interval.rst | 10 +--
 .../v4l/vidioc-subdev-enum-frame-size.rst     | 11 +--
 .../v4l/vidioc-subdev-enum-mbus-code.rst      | 11 +--
 .../media/v4l/vidioc-subdev-g-crop.rst        | 16 ++--
 .../media/v4l/vidioc-subdev-g-fmt.rst         | 17 ++---
 .../v4l/vidioc-subdev-g-frame-interval.rst    | 16 ++--
 .../media/v4l/vidioc-subdev-g-selection.rst   | 17 ++---
 .../media/v4l/vidioc-subdev-querycap.rst      |  9 +--
 .../media/v4l/vidioc-subscribe-event.rst      | 17 ++---
 scripts/kernel-doc                            | 69 +++++++++++++++--
 227 files changed, 1194 insertions(+), 1733 deletions(-)

-- 
2.26.2



^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH v3 1/8] docs: cdomain.py: add support for a new Sphinx 3.1+ tag
  2020-09-25  6:30 [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+ Mauro Carvalho Chehab
@ 2020-09-25  6:30 ` Mauro Carvalho Chehab
  2020-09-25  6:30 ` [PATCH v3 2/8] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
                   ` (5 subsequent siblings)
  6 siblings, 0 replies; 9+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-25  6:30 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-kernel

Since Sphinx 3.0, the C domain code was rewritten, but only
after version 3.1 it got support for setting namespaces on
C domains, with is something that it is required, in order to
document system calls, like ioctl() and others.

As part of changing the documentation subsystem to properly
build with Sphinx 3.1+, add support for such new tag:

	.. c:namespace::"

Such tag optionally replaces the optional "name" tag for functions,
setting a single namespace domain for all C references found
at the file.

With that, it should be possible to convert existing
documentation to be compatible with both Sphinx 1.x/2.x and
3.1+.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/cdomain.py | 55 ++++++++++++++++++++++++++++++++-
 1 file changed, 54 insertions(+), 1 deletion(-)

diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index cbac8e608dc4..35805c44a4fc 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -40,14 +40,56 @@ from sphinx import addnodes
 from sphinx.domains.c import c_funcptr_sig_re, c_sig_re
 from sphinx.domains.c import CObject as Base_CObject
 from sphinx.domains.c import CDomain as Base_CDomain
+from itertools import chain
+import re
 
-__version__  = '1.0'
+__version__  = '1.1'
 
 # Get Sphinx version
 major, minor, patch = sphinx.version_info[:3]
 
+# Namespace to be prepended to the full name
+namespace = None
+
+#
+# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags
+# - Store the namespace if ".. c:namespace::" tag is found
+
+RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
+
+def markup_namespace(match):
+    global namespace
+
+    namespace = match.group(1)
+
+    return ""
+
+def c_markups(app, docname, source):
+    result = ""
+    markup_func = {
+        RE_namespace: markup_namespace,
+    }
+
+    lines = iter(source[0].splitlines(True))
+    for n in lines:
+        match_iterators = [regex.finditer(n) for regex in markup_func]
+        matches = sorted(chain(*match_iterators), key=lambda m: m.start())
+        for m in matches:
+            n = n[:m.start()] + markup_func[m.re](m) + n[m.end():]
+
+        result = result + n
+
+    source[0] = result
+
+#
+# Now implements support for the cdomain namespacing logic
+#
+
 def setup(app):
 
+    # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace::
+    app.connect('source-read', c_markups)
+
     if (major == 1 and minor < 8):
         app.override_domain(CDomain)
     else:
@@ -75,6 +117,8 @@ class CObject(Base_CObject):
         function-like macro, the name of the macro is returned. Otherwise
         ``False`` is returned.  """
 
+        global namespace
+
         if not self.objtype == 'function':
             return False
 
@@ -107,11 +151,16 @@ class CObject(Base_CObject):
             param += nodes.emphasis(argname, argname)
             paramlist += param
 
+        if namespace:
+            fullname = namespace + "." + fullname
+
         return fullname
 
     def handle_signature(self, sig, signode):
         """Transform a C signature into RST nodes."""
 
+        global namespace
+
         fullname = self.handle_func_like_macro(sig, signode)
         if not fullname:
             fullname = super(CObject, self).handle_signature(sig, signode)
@@ -122,6 +171,10 @@ class CObject(Base_CObject):
             else:
                 # FIXME: handle :name: value of other declaration types?
                 pass
+        else:
+            if namespace:
+                fullname = namespace + "." + fullname
+
         return fullname
 
     def add_target_and_index(self, name, sig, signode):
-- 
2.26.2


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v3 2/8] docs: conf.py: disable automarkup for Sphinx 3.x
  2020-09-25  6:30 [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+ Mauro Carvalho Chehab
  2020-09-25  6:30 ` [PATCH v3 1/8] docs: cdomain.py: add support for a new Sphinx 3.1+ tag Mauro Carvalho Chehab
@ 2020-09-25  6:30 ` Mauro Carvalho Chehab
  2020-09-25 12:12   ` [PATCH v3.1 " Mauro Carvalho Chehab
  2020-09-25  6:30 ` [PATCH v3 3/8] scripts: kernel-doc: make it more compatible with " Mauro Carvalho Chehab
                   ` (4 subsequent siblings)
  6 siblings, 1 reply; 9+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-25  6:30 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-kernel

The class types changed after the C domain rewrite on
Sphinx 3.x. Due to that, the automarkup extension is just
generating additional noise when trying to convert structs
and other markups into cross references.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 0a102d57437d..4bae94e756da 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -37,7 +37,7 @@ needs_sphinx = '1.3'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
-              'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
+              'kfigure', 'sphinx.ext.ifconfig',
               'maintainers_include', 'sphinx.ext.autosectionlabel' ]
 
 #
@@ -51,7 +51,7 @@ if major >= 3:
 	in the generated output.
 	''')
 else:
-    extensions.append('cdomain')
+    extensions.append('cdomain', 'automarkup')
 
 # Ensure that autosectionlabel will produce unique names
 autosectionlabel_prefix_document = True
-- 
2.26.2


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v3 3/8] scripts: kernel-doc: make it more compatible with Sphinx 3.x
  2020-09-25  6:30 [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+ Mauro Carvalho Chehab
  2020-09-25  6:30 ` [PATCH v3 1/8] docs: cdomain.py: add support for a new Sphinx 3.1+ tag Mauro Carvalho Chehab
  2020-09-25  6:30 ` [PATCH v3 2/8] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
@ 2020-09-25  6:30 ` Mauro Carvalho Chehab
  2020-09-25  6:30 ` [PATCH v3 4/8] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
                   ` (3 subsequent siblings)
  6 siblings, 0 replies; 9+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-25  6:30 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-kernel

With Sphinx 3.x, the ".. c:type:" tag expects a typedef-like
format, and it accepts just one name afterward.

We actually need to use the new c:struct, c:enum, ...
types when dealing with Sphinx 3.x.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 69 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 62 insertions(+), 7 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 724528f4b7d6..48301ff41ec5 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -271,6 +271,8 @@ if ($#ARGV == -1) {
 }
 
 my $kernelversion;
+my $sphinx_major;
+
 my $dohighlight = "";
 
 my $verbose = 0;
@@ -465,6 +467,43 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
 
 # continue execution near EOF;
 
+# The C domain dialect changed on Sphinx 3. So, we need to check the
+# version in order to produce the right tags.
+sub findprog($)
+{
+	foreach(split(/:/, $ENV{PATH})) {
+		return "$_/$_[0]" if(-x "$_/$_[0]");
+	}
+}
+
+sub get_sphinx_version()
+{
+	my $ver;
+	my $major = 1;
+
+	my $cmd = "sphinx-build";
+	if (!findprog($cmd)) {
+		my $cmd = "sphinx-build3";
+		return $major if (!findprog($cmd));
+	}
+
+	open IN, "$cmd --version 2>&1 |";
+	while (<IN>) {
+		if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
+			$major=$1;
+			last;
+		}
+		# Sphinx 1.2.x uses a different format
+		if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
+			$major=$1;
+			last;
+		}
+	}
+	close IN;
+
+	return $major;
+}
+
 # get kernel version from env
 sub get_kernel_version() {
     my $version = 'unknown kernel version';
@@ -848,7 +887,7 @@ sub output_function_rst(%) {
     my $start = "";
 
     if ($args{'typedef'}) {
-	print ".. c:type:: ". $args{'function'} . "\n\n";
+	print ".. c:function:: ". $args{'function'} . "\n\n";
 	print_lineno($declaration_start_line);
 	print "   **Typedef**: ";
 	$lineprefix = "";
@@ -938,9 +977,14 @@ sub output_enum_rst(%) {
     my ($parameter);
     my $oldprefix = $lineprefix;
     my $count;
-    my $name = "enum " . $args{'enum'};
 
-    print "\n\n.. c:type:: " . $name . "\n\n";
+    if ($sphinx_major < 3) {
+	my $name = "enum " . $args{'enum'};
+	print "\n\n.. c:type:: " . $name . "\n\n";
+    } else {
+	my $name = $args{'enum'};
+	print "\n\n.. c:enum:: " . $name . "\n\n";
+    }
     print_lineno($declaration_start_line);
     $lineprefix = "   ";
     output_highlight_rst($args{'purpose'});
@@ -966,9 +1010,14 @@ sub output_typedef_rst(%) {
     my %args = %{$_[0]};
     my ($parameter);
     my $oldprefix = $lineprefix;
-    my $name = "typedef " . $args{'typedef'};
 
-    print "\n\n.. c:type:: " . $name . "\n\n";
+    if ($sphinx_major < 3) {
+	my $name = "typedef " . $args{'typedef'};
+	print "\n\n.. c:type:: " . $name . "\n\n";
+    } else {
+	my $name = $args{'typedef'};
+	print "\n\n.. c:type:: " . $name . "\n\n";
+    }
     print_lineno($declaration_start_line);
     $lineprefix = "   ";
     output_highlight_rst($args{'purpose'});
@@ -982,9 +1031,14 @@ sub output_struct_rst(%) {
     my %args = %{$_[0]};
     my ($parameter);
     my $oldprefix = $lineprefix;
-    my $name = $args{'type'} . " " . $args{'struct'};
 
-    print "\n\n.. c:type:: " . $name . "\n\n";
+    if ($sphinx_major < 3) {
+	my $name = $args{'type'} . " " . $args{'struct'};
+	print "\n\n.. c:type:: " . $name . "\n\n";
+    } else {
+	my $name = $args{'struct'};
+	print "\n\n.. c:struct:: " . $name . "\n\n";
+    }
     print_lineno($declaration_start_line);
     $lineprefix = "   ";
     output_highlight_rst($args{'purpose'});
@@ -2235,6 +2289,7 @@ sub process_file($) {
 }
 
 
+$sphinx_major = get_sphinx_version();
 $kernelversion = get_kernel_version();
 
 # generate a sequence of code that will splice in highlighting information
-- 
2.26.2


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v3 4/8] media: docs: make CEC documents compatible with Sphinx 3.1+
  2020-09-25  6:30 [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+ Mauro Carvalho Chehab
                   ` (2 preceding siblings ...)
  2020-09-25  6:30 ` [PATCH v3 3/8] scripts: kernel-doc: make it more compatible with " Mauro Carvalho Chehab
@ 2020-09-25  6:30 ` Mauro Carvalho Chehab
  2020-09-25  6:30 ` [PATCH v3 7/8] media: docs: make MC documents more " Mauro Carvalho Chehab
                   ` (2 subsequent siblings)
  6 siblings, 0 replies; 9+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-25  6:30 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Hans Verkuil,
	Mauro Carvalho Chehab, linux-kernel, linux-media

Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../media/cec/cec-func-close.rst              | 10 +++-------
 .../media/cec/cec-func-ioctl.rst              | 11 ++++------
 .../userspace-api/media/cec/cec-func-open.rst | 10 +++-------
 .../userspace-api/media/cec/cec-func-poll.rst | 14 +++++--------
 .../media/cec/cec-ioc-adap-g-caps.rst         | 10 +++++-----
 .../media/cec/cec-ioc-adap-g-conn-info.rst    | 11 +++++-----
 .../media/cec/cec-ioc-adap-g-log-addrs.rst    | 20 ++++++++-----------
 .../media/cec/cec-ioc-adap-g-phys-addr.rst    | 15 +++++++-------
 .../media/cec/cec-ioc-dqevent.rst             | 15 +++++---------
 .../media/cec/cec-ioc-g-mode.rst              | 16 +++++++--------
 .../media/cec/cec-ioc-receive.rst             | 18 ++++++++---------
 11 files changed, 63 insertions(+), 87 deletions(-)

diff --git a/Documentation/userspace-api/media/cec/cec-func-close.rst b/Documentation/userspace-api/media/cec/cec-func-close.rst
index 33c563f414a8..409e70a5f80f 100644
--- a/Documentation/userspace-api/media/cec/cec-func-close.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-close.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _cec-func-close:
 
@@ -11,7 +12,6 @@ Name
 
 cec-close - Close a cec device
 
-
 Synopsis
 ========
 
@@ -19,16 +19,13 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: int close( int fd )
-    :name: cec-close
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
-
+    File descriptor returned by :c:func:`open()`.
 
 Description
 ===========
@@ -36,11 +33,10 @@ Description
 Closes the cec device. Resources associated with the file descriptor are
 freed. The device configuration remain unchanged.
 
-
 Return Value
 ============
 
-:c:func:`close() <cec-close>` returns 0 on success. On error, -1 is returned, and
+:c:func:`close()` returns 0 on success. On error, -1 is returned, and
 ``errno`` is set appropriately. Possible error codes are:
 
 ``EBADF``
diff --git a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
index 3b88230fad80..7c93f86de6cc 100644
--- a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _cec-func-ioctl:
 
@@ -18,15 +19,13 @@ Synopsis
 
     #include <sys/ioctl.h>
 
-
-.. c:function:: int ioctl( int fd, int request, void *argp )
-   :name: cec-ioctl
+``int ioctl(int fd, int request, void *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``request``
     CEC ioctl request code as defined in the cec.h header file, for
@@ -35,11 +34,10 @@ Arguments
 ``argp``
     Pointer to a request-specific structure.
 
-
 Description
 ===========
 
-The :c:func:`ioctl() <cec-ioctl>` function manipulates cec device parameters. The
+The :c:func:`ioctl()` function manipulates cec device parameters. The
 argument ``fd`` must be an open file descriptor.
 
 The ioctl ``request`` code specifies the cec function to be called. It
@@ -51,7 +49,6 @@ their parameters are located in the cec.h header file. All cec ioctl
 requests, their respective function and parameters are specified in
 :ref:`cec-user-func`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/cec/cec-func-open.rst b/Documentation/userspace-api/media/cec/cec-func-open.rst
index 887bfd2a755e..d86563a34b9e 100644
--- a/Documentation/userspace-api/media/cec/cec-func-open.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-open.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _cec-func-open:
 
@@ -18,10 +19,7 @@ Synopsis
 
     #include <fcntl.h>
 
-
 .. c:function:: int open( const char *device_name, int flags )
-   :name: cec-open
-
 
 Arguments
 =========
@@ -42,11 +40,10 @@ Arguments
 
     Other flags have no effect.
 
-
 Description
 ===========
 
-To open a cec device applications call :c:func:`open() <cec-open>` with the
+To open a cec device applications call :c:func:`open()` with the
 desired device name. The function has no side effects; the device
 configuration remain unchanged.
 
@@ -54,11 +51,10 @@ When the device is opened in read-only mode, attempts to modify its
 configuration will result in an error, and ``errno`` will be set to
 EBADF.
 
-
 Return Value
 ============
 
-:c:func:`open() <cec-open>` returns the new file descriptor on success. On error,
+:c:func:`open()` returns the new file descriptor on success. On error,
 -1 is returned, and ``errno`` is set appropriately. Possible error codes
 include:
 
diff --git a/Documentation/userspace-api/media/cec/cec-func-poll.rst b/Documentation/userspace-api/media/cec/cec-func-poll.rst
index 2d87136e9a3f..980bbfc0bcce 100644
--- a/Documentation/userspace-api/media/cec/cec-func-poll.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-poll.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _cec-func-poll:
 
@@ -11,7 +12,6 @@ Name
 
 cec-poll - Wait for some event on a file descriptor
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <sys/poll.h>
 
-
 .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
-   :name: cec-poll
 
 Arguments
 =========
@@ -35,14 +33,13 @@ Arguments
 ``timeout``
    Timeout to wait for events
 
-
 Description
 ===========
 
-With the :c:func:`poll() <cec-poll>` function applications can wait for CEC
+With the :c:func:`poll()` function applications can wait for CEC
 events.
 
-On success :c:func:`poll() <cec-poll>` returns the number of file descriptors
+On success :c:func:`poll()` returns the number of file descriptors
 that have been selected (that is, file descriptors for which the
 ``revents`` field of the respective struct :c:type:`pollfd`
 is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
@@ -53,13 +50,12 @@ then the ``POLLPRI`` flag is set. When the function times out it returns
 a value of zero, on failure it returns -1 and the ``errno`` variable is
 set appropriately.
 
-For more details see the :c:func:`poll() <cec-poll>` manual page.
-
+For more details see the :c:func:`poll()` manual page.
 
 Return Value
 ============
 
-On success, :c:func:`poll() <cec-poll>` returns the number structures which have
+On success, :c:func:`poll()` returns the number structures which have
 non-zero ``revents`` fields, or zero if the call timed out. On error -1
 is returned, and the ``errno`` variable is set appropriately:
 
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
index 7f25365ce0fb..c7309a2fcbce 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_ADAP_G_CAPS:
 
@@ -14,18 +15,18 @@ CEC_ADAP_G_CAPS - Query device capabilities
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp )
-    :name: CEC_ADAP_G_CAPS
+.. c:macro:: CEC_ADAP_G_CAPS
+
+``int ioctl(int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
 
-
 Description
 ===========
 
@@ -62,7 +63,6 @@ returns the information to the application. The ioctl never fails.
       - CEC Framework API version, formatted with the ``KERNEL_VERSION()``
 	macro.
 
-
 .. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
 
 .. _cec-capabilities:
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst
index 6818ddf1495c..13116b0b5c17 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst
@@ -2,6 +2,8 @@
 ..
 .. Copyright 2019 Google LLC
 ..
+.. c:namespace:: CEC
+
 .. _CEC_ADAP_G_CONNECTOR_INFO:
 
 *******************************
@@ -16,18 +18,18 @@ CEC_ADAP_G_CONNECTOR_INFO - Query HDMI connector information
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp )
-    :name: CEC_ADAP_G_CONNECTOR_INFO
+.. c:macro:: CEC_ADAP_G_CONNECTOR_INFO
+
+``int ioctl(int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
 
-
 Description
 ===========
 
@@ -57,7 +59,6 @@ is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set.
     * - }
       -
 
-
 .. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
 
 .. _connector-type:
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
index 1ca893270ae9..c760c07b6b3f 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_ADAP_LOG_ADDRS:
 .. _CEC_ADAP_G_LOG_ADDRS:
@@ -13,21 +14,22 @@ Name
 
 CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp )
-   :name: CEC_ADAP_G_LOG_ADDRS
+.. c:macro:: CEC_ADAP_G_LOG_ADDRS
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp )
-   :name: CEC_ADAP_S_LOG_ADDRS
+``int ioctl(int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp)``
+
+.. c:macro:: CEC_ADAP_S_LOG_ADDRS
+
+``int ioctl(int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`cec_log_addrs`.
@@ -148,7 +150,6 @@ logical address types are already defined will return with error ``EBUSY``.
         give the CEC framework more information about the device type, even
         though the framework won't use it directly in the CEC message.
 
-
 .. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}|
 
 .. _cec-log-addrs-flags:
@@ -185,7 +186,6 @@ logical address types are already defined will return with error ``EBUSY``.
 
 	All other messages are ignored.
 
-
 .. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}|
 
 .. _cec-versions:
@@ -211,7 +211,6 @@ logical address types are already defined will return with error ``EBUSY``.
       - 6
       - CEC version according to the HDMI 2.0 standard.
 
-
 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 
 .. _cec-prim-dev-types:
@@ -257,7 +256,6 @@ logical address types are already defined will return with error ``EBUSY``.
       - 7
       - Use for a video processor device.
 
-
 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 
 .. _cec-log-addr-types:
@@ -306,7 +304,6 @@ logical address types are already defined will return with error ``EBUSY``.
 	Control).
 
 
-
 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 
 .. _cec-all-dev-types-flags:
@@ -348,7 +345,6 @@ logical address types are already defined will return with error ``EBUSY``.
       - This supports the CEC Switch or Video Processing type.
 
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst
index a10443be1b26..fb22f6894f26 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_ADAP_PHYS_ADDR:
 .. _CEC_ADAP_G_PHYS_ADDR:
@@ -13,21 +14,22 @@ Name
 
 CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp )
-    :name: CEC_ADAP_G_PHYS_ADDR
+.. c:macro:: CEC_ADAP_G_PHYS_ADDR
 
-.. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp )
-    :name: CEC_ADAP_S_PHYS_ADDR
+``int ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)``
+
+.. c:macro:: CEC_ADAP_S_PHYS_ADDR
+
+``int ioctl(int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to the CEC address.
@@ -71,7 +73,6 @@ For example, the EDID for each HDMI input of the TV will have a
 different physical address of the form a.0.0.0 that the sources will
 read out and use as their physical address.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
index 3bc81fc5a73f..736fda5ad73d 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_DQEVENT:
 
@@ -11,22 +12,21 @@ Name
 
 CEC_DQEVENT - Dequeue a CEC event
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp )
-    :name: CEC_DQEVENT
+.. c:macro:: CEC_DQEVENT
+
+``int ioctl(int fd, CEC_DQEVENT, struct cec_event *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
 
-
 Description
 ===========
 
@@ -72,7 +72,6 @@ it is guaranteed that the state did change in between the two events.
         the HDMI driver is still configuring the device or because the HDMI
         device was unbound.
 
-
 .. c:type:: cec_event_lost_msgs
 
 .. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}|
@@ -94,7 +93,6 @@ it is guaranteed that the state did change in between the two events.
 	replied to within a second according to the CEC specification,
 	this is more than enough.
 
-
 .. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}|
 
 .. c:type:: cec_event
@@ -130,7 +128,6 @@ it is guaranteed that the state did change in between the two events.
     * - }
       -
 
-
 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 
 .. _cec-events:
@@ -204,7 +201,6 @@ it is guaranteed that the state did change in between the two events.
 	if the 5V is high, then an initial event will be generated for that
 	filehandle.
 
-
 .. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}|
 
 .. _cec-event-flags:
@@ -230,7 +226,6 @@ it is guaranteed that the state did change in between the two events.
         This is an indication that the application cannot keep up.
 
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
index 2093e373c93c..d3387b1fa7c5 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_MODE:
 .. _CEC_G_MODE:
@@ -13,17 +14,19 @@ CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp )
-   :name: CEC_G_MODE
+.. c:macro:: CEC_G_MODE
 
-.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp )
-   :name: CEC_S_MODE
+``int ioctl(int fd, CEC_G_MODE, __u32 *argp)``
+
+.. c:macro:: CEC_S_MODE
+
+``int ioctl(int fd, CEC_S_MODE, __u32 *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to CEC mode.
@@ -101,7 +104,6 @@ Available initiator modes are:
 	then an attempt to become one will return the ``EBUSY`` error code
 	error.
 
-
 Available follower modes are:
 
 .. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}|
@@ -193,7 +195,6 @@ Available follower modes are:
 	the process has the ``CAP_NET_ADMIN`` capability. If that is not
 	set, then the ``EPERM`` error code is returned.
 
-
 Core message processing details:
 
 .. tabularcolumns:: |p{6.6cm}|p{10.9cm}|
@@ -272,7 +273,6 @@ Core message processing details:
 	and then just pass the message on to the follower(s).
 
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
index 9d629d46973c..b2fc051e99f4 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
 
 .. _CEC_TRANSMIT:
 .. _CEC_RECEIVE:
@@ -12,21 +13,22 @@ Name
 
 CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp )
-    :name: CEC_RECEIVE
+.. c:macro:: CEC_RECEIVE
 
-.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp )
-    :name: CEC_TRANSMIT
+``int ioctl(int fd, CEC_RECEIVE, struct cec_msg *argp)``
+
+.. c:macro:: CEC_TRANSMIT
+
+``int ioctl(int fd, CEC_TRANSMIT, struct cec_msg *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <cec-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct cec_msg.
@@ -194,7 +196,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
 	supports this, otherwise it is always 0. This counter is only
 	valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
 
-
 .. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}|
 
 .. _cec-msg-flags:
@@ -228,7 +229,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
 	capability. If that is not set, then the ``EPERM`` error code is
 	returned.
 
-
 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 
 .. _cec-tx-status:
@@ -298,7 +298,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
       - The transmit timed out. This should not normally happen and this
 	indicates a driver problem.
 
-
 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 
 .. _cec-rx-status:
@@ -335,7 +334,6 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
 	reply was interrupted.
 
 
-
 Return Value
 ============
 
-- 
2.26.2


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v3 7/8] media: docs: make MC documents more compatible with Sphinx 3.1+
  2020-09-25  6:30 [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+ Mauro Carvalho Chehab
                   ` (3 preceding siblings ...)
  2020-09-25  6:30 ` [PATCH v3 4/8] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
@ 2020-09-25  6:30 ` Mauro Carvalho Chehab
  2020-09-25  6:30 ` [PATCH v3 8/8] media: docs: make RC " Mauro Carvalho Chehab
  2020-09-25  7:31 ` [PATCH v3 0/8] Improve support for building docs " Mauro Carvalho Chehab
  6 siblings, 0 replies; 9+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-25  6:30 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Alexandre Courbot,
	Hans Verkuil, Mauro Carvalho Chehab, linux-kernel, linux-media

Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../media/mediactl/media-func-close.rst            | 10 +++-------
 .../media/mediactl/media-func-ioctl.rst            | 10 +++-------
 .../media/mediactl/media-func-open.rst             | 10 +++-------
 .../media/mediactl/media-ioc-device-info.rst       | 13 ++++---------
 .../media/mediactl/media-ioc-enum-entities.rst     | 11 ++++-------
 .../media/mediactl/media-ioc-enum-links.rst        | 13 ++++---------
 .../media/mediactl/media-ioc-g-topology.rst        | 14 ++++----------
 .../media/mediactl/media-ioc-request-alloc.rst     | 11 +++++------
 .../media/mediactl/media-ioc-setup-link.rst        | 10 ++++------
 .../media/mediactl/media-request-ioc-queue.rst     |  7 +++----
 .../media/mediactl/media-request-ioc-reinit.rst    |  8 ++++----
 .../userspace-api/media/mediactl/request-api.rst   |  5 +++--
 .../media/mediactl/request-func-close.rst          |  8 ++------
 .../media/mediactl/request-func-ioctl.rst          |  8 ++------
 .../media/mediactl/request-func-poll.rst           | 12 ++++--------
 15 files changed, 52 insertions(+), 98 deletions(-)

diff --git a/Documentation/userspace-api/media/mediactl/media-func-close.rst b/Documentation/userspace-api/media/mediactl/media-func-close.rst
index ec571b34ce69..8ac2443e76c1 100644
--- a/Documentation/userspace-api/media/mediactl/media-func-close.rst
+++ b/Documentation/userspace-api/media/mediactl/media-func-close.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media-func-close:
 
@@ -11,7 +12,6 @@ Name
 
 media-close - Close a media device
 
-
 Synopsis
 ========
 
@@ -19,16 +19,13 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: int close( int fd )
-    :name: mc-close
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <mc-open>`.
-
+    File descriptor returned by :c:func:`open()`.
 
 Description
 ===========
@@ -36,11 +33,10 @@ Description
 Closes the media device. Resources associated with the file descriptor
 are freed. The device configuration remain unchanged.
 
-
 Return Value
 ============
 
-:ref:`close() <media-func-close>` returns 0 on success. On error, -1 is returned, and
+:c:func:`close()` returns 0 on success. On error, -1 is returned, and
 ``errno`` is set appropriately. Possible error codes are:
 
 EBADF
diff --git a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst
index 35ed549bec0e..9e9a838f4795 100644
--- a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst
+++ b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media-func-ioctl:
 
@@ -11,7 +12,6 @@ Name
 
 media-ioctl - Control a media device
 
-
 Synopsis
 ========
 
@@ -19,15 +19,13 @@ Synopsis
 
     #include <sys/ioctl.h>
 
-
-.. c:function:: int ioctl( int fd, int request, void *argp )
-    :name: mc-ioctl
+``int ioctl(int fd, int request, void *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :c:func:`open() <mc-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``request``
     Media ioctl request code as defined in the media.h header file, for
@@ -36,7 +34,6 @@ Arguments
 ``argp``
     Pointer to a request-specific structure.
 
-
 Description
 ===========
 
@@ -52,7 +49,6 @@ their parameters are located in the media.h header file. All media ioctl
 requests, their respective function and parameters are specified in
 :ref:`media-user-func`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-func-open.rst b/Documentation/userspace-api/media/mediactl/media-func-open.rst
index 2c2595157ea3..24487cb0a308 100644
--- a/Documentation/userspace-api/media/mediactl/media-func-open.rst
+++ b/Documentation/userspace-api/media/mediactl/media-func-open.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media-func-open:
 
@@ -11,7 +12,6 @@ Name
 
 media-open - Open a media device
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <fcntl.h>
 
-
 .. c:function:: int open( const char *device_name, int flags )
-    :name: mc-open
 
 Arguments
 =========
@@ -33,11 +31,10 @@ Arguments
     Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``.
     Other flags have no effect.
 
-
 Description
 ===========
 
-To open a media device applications call :ref:`open() <media-func-open>` with the
+To open a media device applications call :c:func:`open()` with the
 desired device name. The function has no side effects; the device
 configuration remain unchanged.
 
@@ -45,11 +42,10 @@ When the device is opened in read-only mode, attempts to modify its
 configuration will result in an error, and ``errno`` will be set to
 EBADF.
 
-
 Return Value
 ============
 
-:ref:`open() <func-open>` returns the new file descriptor on success. On error,
+:c:func:`open()` returns the new file descriptor on success. On error,
 -1 is returned, and ``errno`` is set appropriately. Possible error codes
 are:
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst
index cde1ddfc0bfb..0c4c5d2cfcb2 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_device_info:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_DEVICE_INFO - Query device information
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp )
-    :name: MEDIA_IOC_DEVICE_INFO
+.. c:macro:: MEDIA_IOC_DEVICE_INFO
 
+``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`media_device_info`.
 
-
 Description
 ===========
 
@@ -38,7 +37,6 @@ a struct :c:type:`media_device_info`. The driver
 fills the structure and returns the information to the application. The
 ioctl never fails.
 
-
 .. c:type:: media_device_info
 
 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -48,7 +46,6 @@ ioctl never fails.
     :stub-columns: 0
     :widths:       1 1 2
 
-
     *  -  char
        -  ``driver``\ [16]
        -  Name of the driver implementing the media API as a NUL-terminated
@@ -94,7 +91,6 @@ ioctl never fails.
        -  Reserved for future extensions. Drivers and applications must set
 	  this array to zero.
 
-
 The ``serial`` and ``bus_info`` fields can be used to distinguish
 between multiple instances of otherwise identical hardware. The serial
 number takes precedence when provided and can be assumed to be unique.
@@ -102,7 +98,6 @@ If the serial number is an empty string, the ``bus_info`` field can be
 used instead. The ``bus_info`` field is guaranteed to be unique, but can
 vary across reboots or device unplug/replug.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
index 93e35f198f47..92dd8ecd538c 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_enum_entities:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp )
-    :name: MEDIA_IOC_ENUM_ENTITIES
+.. c:macro:: MEDIA_IOC_ENUM_ENTITIES
 
+``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`media_entity_desc`.
 
-
 Description
 ===========
 
@@ -49,7 +48,6 @@ Entity IDs can be non-contiguous. Applications must *not* try to
 enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
 id's until they get an error.
 
-
 .. c:type:: media_entity_desc
 
 .. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}|
@@ -136,7 +134,6 @@ id's until they get an error.
     *  - }
        -
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst
index f3e94c7b5dc3..3bc98a6a2ec5 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_enum_links:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp )
-    :name: MEDIA_IOC_ENUM_LINKS
+.. c:macro:: MEDIA_IOC_ENUM_LINKS
 
+``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`media_links_enum`.
 
-
 Description
 ===========
 
@@ -53,7 +52,6 @@ outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
 Only forward links that originate at one of the entity's source pads are
 returned during the enumeration process.
 
-
 .. c:type:: media_links_enum
 
 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -82,7 +80,6 @@ returned during the enumeration process.
        -  Reserved for future extensions. Drivers and applications must set
           the array to zero.
 
-
 .. c:type:: media_pad_desc
 
 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -110,7 +107,6 @@ returned during the enumeration process.
           the array to zero.
 
 
-
 .. c:type:: media_link_desc
 
 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -137,7 +133,6 @@ returned during the enumeration process.
        -  Reserved for future extensions. Drivers and applications must set
           the array to zero.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst
index 9b7d2296b7fd..8f8b3b586edd 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_g_topology:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp )
-    :name: MEDIA_IOC_G_TOPOLOGY
+.. c:macro:: MEDIA_IOC_G_TOPOLOGY
 
+``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`media_v2_topology`.
 
-
 Description
 ===========
 
@@ -120,7 +119,6 @@ desired arrays with the media graph elements.
 	  converted to a 64-bits integer. It can be zero. if zero, the ioctl
 	  won't store the links. It will just update ``num_links``
 
-
 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 
 .. c:type:: media_v2_entity
@@ -158,7 +156,6 @@ desired arrays with the media graph elements.
        -  Reserved for future extensions. Drivers and applications must set
 	  this array to zero.
 
-
 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 
 .. c:type:: media_v2_interface
@@ -192,7 +189,6 @@ desired arrays with the media graph elements.
        -  Used only for device node interfaces. See
 	  :c:type:`media_v2_intf_devnode` for details.
 
-
 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 
 .. c:type:: media_v2_intf_devnode
@@ -245,7 +241,6 @@ desired arrays with the media graph elements.
        -  Reserved for future extensions. Drivers and applications must set
 	  this array to zero.
 
-
 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
 
 .. c:type:: media_v2_link
@@ -282,7 +277,6 @@ desired arrays with the media graph elements.
        -  Reserved for future extensions. Drivers and applications must set
 	  this array to zero.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst
index ea05ff0c5382..9195b4b8bf20 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_request_alloc:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_REQUEST_ALLOC - Allocate a request
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp )
-    :name: MEDIA_IOC_REQUEST_ALLOC
+.. c:macro:: MEDIA_IOC_REQUEST_ALLOC
 
+``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to an integer.
 
-
 Description
 ===========
 
@@ -51,7 +50,7 @@ Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait
 for the request to complete.
 
 The request will remain allocated until all the file descriptors associated
-with it are closed by :ref:`close() <request-func-close>` and the driver no
+with it are closed by :c:func:`close()` and the driver no
 longer uses the request internally. See also
 :ref:`here <media-request-life-time>` for more information.
 
diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst
index e2aa51015783..23208300cb61 100644
--- a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst
+++ b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_ioc_setup_link:
 
@@ -11,24 +12,22 @@ Name
 
 MEDIA_IOC_SETUP_LINK - Modify the properties of a link
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp )
-    :name: MEDIA_IOC_SETUP_LINK
+.. c:macro:: MEDIA_IOC_SETUP_LINK
 
+``int ioctl(int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp)``
 
 Arguments
 =========
 
 ``fd``
-    File descriptor returned by :ref:`open() <media-func-open>`.
+    File descriptor returned by :c:func:`open()`.
 
 ``argp``
     Pointer to struct :c:type:`media_link_desc`.
 
-
 Description
 ===========
 
@@ -53,7 +52,6 @@ non-dynamic link will return an ``EBUSY`` error code.
 If the specified link can't be found the driver returns with an ``EINVAL``
 error code.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst
index ca1b33196242..04b33db2bb45 100644
--- a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst
+++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_request_ioc_queue:
 
@@ -11,13 +12,12 @@ Name
 
 MEDIA_REQUEST_IOC_QUEUE - Queue a request
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE )
-    :name: MEDIA_REQUEST_IOC_QUEUE
+.. c:macro:: MEDIA_REQUEST_IOC_QUEUE
 
+``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)``
 
 Arguments
 =========
@@ -25,7 +25,6 @@ Arguments
 ``request_fd``
     File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
 
-
 Description
 ===========
 
diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst
index cfd503bdef70..57567b87b985 100644
--- a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst
+++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media_request_ioc_reinit:
 
@@ -11,13 +12,12 @@ Name
 
 MEDIA_REQUEST_IOC_REINIT - Re-initialize a request
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT )
-    :name: MEDIA_REQUEST_IOC_REINIT
+.. c:macro:: MEDIA_REQUEST_IOC_REINIT
 
+``int ioctl(int request_fd, MEDIA_REQUEST_IOC_REINIT)``
 
 Arguments
 =========
@@ -33,7 +33,7 @@ this request ioctl can be used to re-initialize a previously allocated
 request.
 
 Re-initializing a request will clear any existing data from the request.
-This avoids having to :ref:`close() <request-func-close>` a completed
+This avoids having to :c:func:`close()` a completed
 request and allocate a new request. Instead the completed request can just
 be re-initialized and it is ready to be used again.
 
diff --git a/Documentation/userspace-api/media/mediactl/request-api.rst b/Documentation/userspace-api/media/mediactl/request-api.rst
index c0fa4dbb2b28..6c4cbd9f08a5 100644
--- a/Documentation/userspace-api/media/mediactl/request-api.rst
+++ b/Documentation/userspace-api/media/mediactl/request-api.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _media-request-api:
 
@@ -93,7 +94,7 @@ regardless of whether a request is in use or not.
    Setting the same control through a request and also directly can lead to
    undefined behavior!
 
-User-space can :ref:`poll() <request-func-poll>` a request file descriptor in
+User-space can :c:func:`poll()` a request file descriptor in
 order to wait until the request completes. A request is considered complete
 once all its associated buffers are available for dequeuing and all the
 associated controls have been updated with the values at the time of completion.
@@ -115,7 +116,7 @@ Recycling and Destruction
 -------------------------
 
 Finally, a completed request can either be discarded or be reused. Calling
-:ref:`close() <request-func-close>` on a request file descriptor will make
+:c:func:`close()` on a request file descriptor will make
 that file descriptor unusable and the request will be freed once it is no
 longer in use by the kernel. That is, if the request is queued and then the
 file descriptor is closed, then it won't be freed until the driver completed
diff --git a/Documentation/userspace-api/media/mediactl/request-func-close.rst b/Documentation/userspace-api/media/mediactl/request-func-close.rst
index 04e00bb9defd..f4b8eb385ad7 100644
--- a/Documentation/userspace-api/media/mediactl/request-func-close.rst
+++ b/Documentation/userspace-api/media/mediactl/request-func-close.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC.request
 
 .. _request-func-close:
 
@@ -11,7 +12,6 @@ Name
 
 request-close - Close a request file descriptor
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: int close( int fd )
-    :name: req-close
 
 Arguments
 =========
@@ -29,7 +27,6 @@ Arguments
 ``fd``
     File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
 
-
 Description
 ===========
 
@@ -38,11 +35,10 @@ are freed once all file descriptors associated with the request are closed
 and the driver has completed the request.
 See :ref:`here <media-request-life-time>` for more information.
 
-
 Return Value
 ============
 
-:ref:`close() <request-func-close>` returns 0 on success. On error, -1 is
+:c:func:`close()` returns 0 on success. On error, -1 is
 returned, and ``errno`` is set appropriately. Possible error codes are:
 
 EBADF
diff --git a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst
index 1e1c5edb860c..4fb3d2ef32d1 100644
--- a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst
+++ b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _request-func-ioctl:
 
@@ -11,7 +12,6 @@ Name
 
 request-ioctl - Control a request file descriptor
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <sys/ioctl.h>
 
-
-.. c:function:: int ioctl( int fd, int cmd, void *argp )
-    :name: req-ioctl
+``int ioctl(int fd, int cmd, void *argp)``
 
 Arguments
 =========
@@ -36,7 +34,6 @@ Arguments
 ``argp``
     Pointer to a request-specific structure.
 
-
 Description
 ===========
 
@@ -52,7 +49,6 @@ their parameters are located in the media.h header file. All request ioctl
 commands, their respective function and parameters are specified in
 :ref:`media-user-func`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/mediactl/request-func-poll.rst b/Documentation/userspace-api/media/mediactl/request-func-poll.rst
index 92947213d3d5..ce0043dbe7da 100644
--- a/Documentation/userspace-api/media/mediactl/request-func-poll.rst
+++ b/Documentation/userspace-api/media/mediactl/request-func-poll.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: MC
 
 .. _request-func-poll:
 
@@ -11,7 +12,6 @@ Name
 
 request-poll - Wait for some event on a file descriptor
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <sys/poll.h>
 
-
 .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
-   :name: request-poll
 
 Arguments
 =========
@@ -35,14 +33,13 @@ Arguments
 ``timeout``
    Timeout to wait for events
 
-
 Description
 ===========
 
-With the :c:func:`poll() <request-func-poll>` function applications can wait
+With the :c:func:`poll()` function applications can wait
 for a request to complete.
 
-On success :c:func:`poll() <request-func-poll>` returns the number of file
+On success :c:func:`poll()` returns the number of file
 descriptors that have been selected (that is, file descriptors for which the
 ``revents`` field of the respective struct :c:type:`pollfd`
 is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents``
@@ -53,11 +50,10 @@ set appropriately.
 Attempting to poll for a request that is not yet queued will
 set the ``POLLERR`` flag in ``revents``.
 
-
 Return Value
 ============
 
-On success, :c:func:`poll() <request-func-poll>` returns the number of
+On success, :c:func:`poll()` returns the number of
 structures which have non-zero ``revents`` fields, or zero if the call
 timed out. On error -1 is returned, and the ``errno`` variable is set
 appropriately:
-- 
2.26.2


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* [PATCH v3 8/8] media: docs: make RC documents more compatible with Sphinx 3.1+
  2020-09-25  6:30 [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+ Mauro Carvalho Chehab
                   ` (4 preceding siblings ...)
  2020-09-25  6:30 ` [PATCH v3 7/8] media: docs: make MC documents more " Mauro Carvalho Chehab
@ 2020-09-25  6:30 ` Mauro Carvalho Chehab
  2020-09-25  7:31 ` [PATCH v3 0/8] Improve support for building docs " Mauro Carvalho Chehab
  6 siblings, 0 replies; 9+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-25  6:30 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Mauro Carvalho Chehab,
	Sean Young, linux-kernel, linux-media

Sphinx 3.x broke support for the cdomain.py extension, as the
c domain code was rewritten. Due to that, the c tags need to
be re-written, in order to use the new c domain notation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../userspace-api/media/rc/lirc-get-features.rst   |  9 ++++-----
 .../userspace-api/media/rc/lirc-get-rec-mode.rst   | 12 +++++++-----
 .../media/rc/lirc-get-rec-resolution.rst           |  8 ++++----
 .../userspace-api/media/rc/lirc-get-send-mode.rst  | 14 +++++++-------
 .../userspace-api/media/rc/lirc-get-timeout.rst    | 13 +++++++------
 Documentation/userspace-api/media/rc/lirc-read.rst | 10 +++-------
 .../media/rc/lirc-set-measure-carrier-mode.rst     |  8 ++++----
 .../media/rc/lirc-set-rec-carrier-range.rst        |  6 ++++--
 .../media/rc/lirc-set-rec-carrier.rst              |  8 ++++----
 .../media/rc/lirc-set-rec-timeout-reports.rst      |  8 ++++----
 .../media/rc/lirc-set-rec-timeout.rst              | 13 +++++++------
 .../media/rc/lirc-set-send-carrier.rst             |  8 ++++----
 .../media/rc/lirc-set-send-duty-cycle.rst          |  8 ++++----
 .../media/rc/lirc-set-transmitter-mask.rst         |  8 ++++----
 .../media/rc/lirc-set-wideband-receiver.rst        |  8 ++++----
 .../userspace-api/media/rc/lirc-write.rst          |  7 ++-----
 16 files changed, 73 insertions(+), 75 deletions(-)

diff --git a/Documentation/userspace-api/media/rc/lirc-get-features.rst b/Documentation/userspace-api/media/rc/lirc-get-features.rst
index 6846ae99848c..66a243dbd437 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-features.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-features.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_get_features:
 
@@ -14,8 +15,9 @@ LIRC_GET_FEATURES - Get the underlying hardware device's features
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_FEATURES, __u32 *features)
-    :name: LIRC_GET_FEATURES
+.. c:macro:: LIRC_GET_FEATURES
+
+``int ioctl(int fd, LIRC_GET_FEATURES, __u32 *features)``
 
 Arguments
 =========
@@ -26,11 +28,9 @@ Arguments
 ``features``
     Bitmask with the LIRC features.
 
-
 Description
 ===========
 
-
 Get the underlying hardware device's features. If a driver does not
 announce support of certain features, calling of the corresponding ioctls
 is undefined.
@@ -184,7 +184,6 @@ LIRC features
 
     Unused. Kept just to avoid breaking uAPI.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
index e8f397a87331..188478ed1233 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_get_rec_mode:
 .. _lirc_set_rec_mode:
@@ -15,11 +16,13 @@ LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 *mode)
-	:name: LIRC_GET_REC_MODE
+.. c:macro:: LIRC_GET_REC_MODE
 
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 *mode)
-	:name: LIRC_SET_REC_MODE
+``int ioctl(int fd, LIRC_GET_REC_MODE, __u32 *mode)``
+
+.. c:macro:: LIRC_SET_REC_MODE
+
+``int ioctl(int fd, LIRC_SET_REC_MODE, __u32 *mode)``
 
 Arguments
 =========
@@ -47,7 +50,6 @@ Return Value
     :header-rows:  0
     :stub-columns: 0
 
-
     -  .. row 1
 
        -  ``ENODEV``
diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
index 3f08aa7c24a9..e29445c5ce16 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_get_rec_resolution:
 
@@ -14,8 +15,9 @@ LIRC_GET_REC_RESOLUTION - Obtain the value of receive resolution, in microsecond
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds)
-    :name: LIRC_GET_REC_RESOLUTION
+.. c:macro:: LIRC_GET_REC_RESOLUTION
+
+``int ioctl(int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds)``
 
 Arguments
 =========
@@ -26,7 +28,6 @@ Arguments
 ``microseconds``
     Resolution, in microseconds.
 
-
 Description
 ===========
 
@@ -38,7 +39,6 @@ This ioctl returns the integer value with such resolution, with can be
 used by userspace applications like lircd to automatically adjust the
 tolerance value.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
index f93b30c92193..77472fb5608a 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_get_send_mode:
 .. _lirc_set_send_mode:
@@ -15,11 +16,13 @@ LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *mode )
-    :name: LIRC_GET_SEND_MODE
+.. c:macro:: LIRC_GET_SEND_MODE
 
-.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *mode )
-    :name: LIRC_SET_SEND_MODE
+``int ioctl(int fd, LIRC_GET_SEND_MODE, __u32 *mode)``
+
+.. c:macro:: LIRC_SET_SEND_MODE
+
+``int ioctl(int fd, LIRC_SET_SEND_MODE, __u32 *mode)``
 
 Arguments
 =========
@@ -30,7 +33,6 @@ Arguments
 ``mode``
     The mode used for transmitting.
 
-
 Description
 ===========
 
@@ -44,14 +46,12 @@ modes the driver supports.
 Return Value
 ============
 
-
 .. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
 
 .. flat-table::
     :header-rows:  0
     :stub-columns: 0
 
-
     -  .. row 1
 
        -  ``ENODEV``
diff --git a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
index ec191a383d75..f5f3e06d6206 100644
--- a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
+++ b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_get_min_timeout:
 .. _lirc_get_max_timeout:
@@ -16,11 +17,13 @@ range for IR receive.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout)
-    :name: LIRC_GET_MIN_TIMEOUT
+.. c:macro:: LIRC_GET_MIN_TIMEOUT
 
-.. c:function:: int ioctl( int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout)
-    :name: LIRC_GET_MAX_TIMEOUT
+``int ioctl(int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout)``
+
+.. c:macro:: LIRC_GET_MAX_TIMEOUT
+
+``int ioctl(int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout)``
 
 Arguments
 =========
@@ -31,7 +34,6 @@ Arguments
 ``timeout``
     Timeout, in microseconds.
 
-
 Description
 ===========
 
@@ -47,7 +49,6 @@ that can be set.
    both ioctls will return the same value even though the timeout
    cannot be changed via :ref:`LIRC_SET_REC_TIMEOUT`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-read.rst b/Documentation/userspace-api/media/rc/lirc-read.rst
index b94a349bd99e..d589560214f4 100644
--- a/Documentation/userspace-api/media/rc/lirc-read.rst
+++ b/Documentation/userspace-api/media/rc/lirc-read.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc-read:
 
@@ -11,7 +12,6 @@ Name
 
 lirc-read - Read from a LIRC device
 
-
 Synopsis
 ========
 
@@ -19,10 +19,7 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: ssize_t read( int fd, void *buf, size_t count )
-    :name: lirc-read
-
 
 Arguments
 =========
@@ -39,9 +36,9 @@ Arguments
 Description
 ===========
 
-:ref:`read() <lirc-read>` attempts to read up to ``count`` bytes from file
+:c:func:`read()` attempts to read up to ``count`` bytes from file
 descriptor ``fd`` into the buffer starting at ``buf``.  If ``count`` is zero,
-:ref:`read() <lirc-read>` returns zero and has no other results. If ``count``
+:c:func:`read()` returns zero and has no other results. If ``count``
 is greater than ``SSIZE_MAX``, the result is unspecified.
 
 The exact format of the data depends on what :ref:`lirc_modes` a driver
@@ -59,7 +56,6 @@ by hardware decoders. The :c:type:`rc_proto` member is set to the
 used for transmission, and ``scancode`` to the decoded scancode,
 and the ``keycode`` set to the keycode or ``KEY_RESERVED``.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
index 820d6bf28c1c..9bf9811a905a 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_measure_carrier_mode:
 
@@ -14,8 +15,9 @@ LIRC_SET_MEASURE_CARRIER_MODE - enable or disable measure mode
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable )
-    :name: LIRC_SET_MEASURE_CARRIER_MODE
+.. c:macro:: LIRC_SET_MEASURE_CARRIER_MODE
+
+``int ioctl(int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable)``
 
 Arguments
 =========
@@ -27,7 +29,6 @@ Arguments
     enable = 1 means enable measure mode, enable = 0 means disable measure
     mode.
 
-
 Description
 ===========
 
@@ -37,7 +38,6 @@ Enable or disable measure mode. If enabled, from the next key
 press on, the driver will send ``LIRC_MODE2_FREQUENCY`` packets. By
 default this should be turned off.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
index e33e6a320b7a..530bc223930a 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_rec_carrier_range:
 
@@ -15,8 +16,9 @@ IR receive.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency )
-    :name: LIRC_SET_REC_CARRIER_RANGE
+.. c:macro:: LIRC_SET_REC_CARRIER_RANGE
+
+``int ioctl(int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency)``
 
 Arguments
 =========
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
index a6784d5e59c8..28c928f1cc14 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_rec_carrier:
 
@@ -11,12 +12,12 @@ Name
 
 LIRC_SET_REC_CARRIER - Set carrier used to modulate IR receive.
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER, __u32 *frequency )
-    :name: LIRC_SET_REC_CARRIER
+.. c:macro:: LIRC_SET_REC_CARRIER
+
+``int ioctl(int fd, LIRC_SET_REC_CARRIER, __u32 *frequency)``
 
 Arguments
 =========
@@ -37,7 +38,6 @@ Set receive carrier used to modulate IR PWM pulses and spaces.
    If called together with :ref:`LIRC_SET_REC_CARRIER_RANGE`, this ioctl
    sets the upper bound frequency that will be recognized by the device.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst
index 55be65df7d5a..83e7155c5796 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_rec_timeout_reports:
 
@@ -14,8 +15,9 @@ LIRC_SET_REC_TIMEOUT_REPORTS - enable or disable timeout reports for IR receive
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable )
-    :name: LIRC_SET_REC_TIMEOUT_REPORTS
+.. c:macro:: LIRC_SET_REC_TIMEOUT_REPORTS
+
+``int ioctl(int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable)``
 
 Arguments
 =========
@@ -27,7 +29,6 @@ Arguments
     enable = 1 means enable timeout report, enable = 0 means disable timeout
     reports.
 
-
 Description
 ===========
 
@@ -40,7 +41,6 @@ should be turned off.
 
    This ioctl is only valid for :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
index e91a0daecde6..8f3f9adf54ab 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_rec_timeout:
 .. _lirc_get_rec_timeout:
@@ -15,11 +16,13 @@ LIRC_GET_REC_TIMEOUT/LIRC_SET_REC_TIMEOUT - Get/set the integer value for IR ina
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout )
-    :name: LIRC_GET_REC_TIMEOUT
+.. c:macro:: LIRC_GET_REC_TIMEOUT
 
-.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout )
-    :name: LIRC_SET_REC_TIMEOUT
+``int ioctl(int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout)``
+
+.. c:macro:: LIRC_SET_REC_TIMEOUT
+
+``int ioctl(int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout)``
 
 Arguments
 =========
@@ -30,7 +33,6 @@ Arguments
 ``timeout``
     Timeout, in microseconds.
 
-
 Description
 ===========
 
@@ -45,7 +47,6 @@ given value should be set.
 
    The range of supported timeout is given by :ref:`LIRC_GET_MIN_TIMEOUT`.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
index e199aac7d8e0..e3810ba58746 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_send_carrier:
 
@@ -11,12 +12,12 @@ Name
 
 LIRC_SET_SEND_CARRIER - Set send carrier used to modulate IR TX.
 
-
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency )
-    :name: LIRC_SET_SEND_CARRIER
+.. c:macro:: LIRC_SET_SEND_CARRIER
+
+``int ioctl(int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency)``
 
 Arguments
 =========
@@ -32,7 +33,6 @@ Description
 
 Set send carrier used to modulate IR PWM pulses and spaces.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
index a9074f4fb058..52a072529af9 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_send_duty_cycle:
 
@@ -15,8 +16,9 @@ IR transmit.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle)
-    :name: LIRC_SET_SEND_DUTY_CYCLE
+.. c:macro:: LIRC_SET_SEND_DUTY_CYCLE
+
+``int ioctl(int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle)``
 
 Arguments
 =========
@@ -28,7 +30,6 @@ Arguments
     Duty cicle, describing the pulse width in percent (from 1 to 99) of
     the total cycle. Values 0 and 100 are reserved.
 
-
 Description
 ===========
 
@@ -38,7 +39,6 @@ Currently, no special meaning is defined for 0 or 100, but this
 could be used to switch off carrier generation in the future, so
 these values should be reserved.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
index 1f5527427281..68f4cc2e3ae3 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_transmitter_mask:
 
@@ -14,8 +15,9 @@ LIRC_SET_TRANSMITTER_MASK - Enables send codes on a given set of transmitters
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask )
-    :name: LIRC_SET_TRANSMITTER_MASK
+.. c:macro:: LIRC_SET_TRANSMITTER_MASK
+
+``int ioctl(int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask)``
 
 Arguments
 =========
@@ -26,7 +28,6 @@ Arguments
 ``mask``
     Mask with channels to enable tx. Channel 0 is the least significant bit.
 
-
 Description
 ===========
 
@@ -42,7 +43,6 @@ When an invalid bit mask is given, i.e. a bit is set, even though the device
 does not have so many transitters, then this ioctl returns the number of
 available transitters and does nothing otherwise.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
index 2c43b620b3f3..be5321c4a91f 100644
--- a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
+++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc_set_wideband_receiver:
 
@@ -14,8 +15,9 @@ LIRC_SET_WIDEBAND_RECEIVER - enable wide band receiver.
 Synopsis
 ========
 
-.. c:function:: int ioctl( int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable )
-    :name: LIRC_SET_WIDEBAND_RECEIVER
+.. c:macro:: LIRC_SET_WIDEBAND_RECEIVER
+
+``int ioctl(int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable)``
 
 Arguments
 =========
@@ -27,7 +29,6 @@ Arguments
     enable = 1 means enable wideband receiver, enable = 0 means disable
     wideband receiver.
 
-
 Description
 ===========
 
@@ -47,7 +48,6 @@ reduced range of reception.
     carrier reports. Trying to disable wide band receiver while carrier
     reports are active will do nothing.
 
-
 Return Value
 ============
 
diff --git a/Documentation/userspace-api/media/rc/lirc-write.rst b/Documentation/userspace-api/media/rc/lirc-write.rst
index 421de2cfa4ca..c1c3230d4fd6 100644
--- a/Documentation/userspace-api/media/rc/lirc-write.rst
+++ b/Documentation/userspace-api/media/rc/lirc-write.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
 
 .. _lirc-write:
 
@@ -11,7 +12,6 @@ Name
 
 lirc-write - Write to a LIRC device
 
-
 Synopsis
 ========
 
@@ -19,9 +19,7 @@ Synopsis
 
     #include <unistd.h>
 
-
 .. c:function:: ssize_t write( int fd, void *buf, size_t count )
-    :name: lirc-write
 
 Arguments
 =========
@@ -38,7 +36,7 @@ Arguments
 Description
 ===========
 
-:ref:`write() <lirc-write>` writes up to ``count`` bytes to the device
+:c:func:`write()` writes up to ``count`` bytes to the device
 referenced by the file descriptor ``fd`` from the buffer starting at
 ``buf``.
 
@@ -64,7 +62,6 @@ for the protocol or the scancode is not valid for the specified protocol,
 ``EINVAL`` is returned. The write function blocks until the scancode
 is transmitted by the hardware.
 
-
 Return Value
 ============
 
-- 
2.26.2


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* Re: [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+
  2020-09-25  6:30 [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+ Mauro Carvalho Chehab
                   ` (5 preceding siblings ...)
  2020-09-25  6:30 ` [PATCH v3 8/8] media: docs: make RC " Mauro Carvalho Chehab
@ 2020-09-25  7:31 ` Mauro Carvalho Chehab
  6 siblings, 0 replies; 9+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-25  7:31 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: linux-kernel, Jonathan Corbet, Niklas Söderlund,
	Alexandre Courbot, Arnd Bergmann, Boris Brezillon,
	Ezequiel Garcia, Hans Verkuil, Helen Koike, Jacopo Mondi,
	Jernej Skrabec, Jian-Jia Su, Laurent Pinchart,
	Mauro Carvalho Chehab, Michael Tretter, Paul Kocialkowski,
	Philipp Zabel, Randy Dunlap, Ricardo Ribalda, Sakari Ailus,
	Sean Young, Sergey Senozhatsky, Tomasz Figa, linux-media

Em Fri, 25 Sep 2020 08:30:38 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Sphinx 3.x new c domain code broke the doc build on several ways:
> 
> - it broke the cdomains.py extension that were giving namespace
>   support for C references;
> - it broke the automarkup script;
> - it broke c:type references that kernel-doc and other parts of the
>   kernel were using to do cross-references with C declarations.
> 
> This series address only part of those issues. It halves the number
> of warnings produced when Spinx 3.x is used.  Yet, we still
> have 1.7 K warnings.

At least some of the warnings seem to be due to some issues at
Sphinx 3.x. I opened an issue to Sphinx upstream:

	https://github.com/sphinx-doc/sphinx/issues/8241

Thanks,
Mauro

^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH v3.1 2/8] docs: conf.py: disable automarkup for Sphinx 3.x
  2020-09-25  6:30 ` [PATCH v3 2/8] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
@ 2020-09-25 12:12   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 9+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-25 12:12 UTC (permalink / raw)
  To: Linux Doc Mailing List; +Cc: Jonathan Corbet, linux-kernel

The class types changed after the C domain rewrite on
Sphinx 3.x. Due to that, the automarkup extension is just
generating additional noise when trying to convert structs
and other markups into cross references.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

---

v3.1: Sphinx actually complains when append has more than one
item. So, let's call extensions.append() twice.

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 0a102d57437d..3875401486de 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -37,7 +37,7 @@ needs_sphinx = '1.3'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
-              'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
+              'kfigure', 'sphinx.ext.ifconfig',
               'maintainers_include', 'sphinx.ext.autosectionlabel' ]
 
 #
@@ -52,6 +52,7 @@ if major >= 3:
 	''')
 else:
     extensions.append('cdomain')
+    extensions.append('automarkup')
 
 # Ensure that autosectionlabel will produce unique names
 autosectionlabel_prefix_document = True

^ permalink raw reply related	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2020-09-25 12:12 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-09-25  6:30 [PATCH v3 0/8] Improve support for building docs with Sphinx 3.1+ Mauro Carvalho Chehab
2020-09-25  6:30 ` [PATCH v3 1/8] docs: cdomain.py: add support for a new Sphinx 3.1+ tag Mauro Carvalho Chehab
2020-09-25  6:30 ` [PATCH v3 2/8] docs: conf.py: disable automarkup for Sphinx 3.x Mauro Carvalho Chehab
2020-09-25 12:12   ` [PATCH v3.1 " Mauro Carvalho Chehab
2020-09-25  6:30 ` [PATCH v3 3/8] scripts: kernel-doc: make it more compatible with " Mauro Carvalho Chehab
2020-09-25  6:30 ` [PATCH v3 4/8] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
2020-09-25  6:30 ` [PATCH v3 7/8] media: docs: make MC documents more " Mauro Carvalho Chehab
2020-09-25  6:30 ` [PATCH v3 8/8] media: docs: make RC " Mauro Carvalho Chehab
2020-09-25  7:31 ` [PATCH v3 0/8] Improve support for building docs " Mauro Carvalho Chehab

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).