* [PATCH 0/2] Start supporting builds with Sphinx 3.1+
[not found] <20200924090230.6f3b0ca1@coco.lan>
@ 2020-09-24 11:22 ` Mauro Carvalho Chehab
2020-09-24 11:22 ` [PATCH 1/2] docs: cdomain.py: add support for two new Sphinx 3.1+ tags Mauro Carvalho Chehab
2020-09-24 11:22 ` [PATCH 2/2] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
0 siblings, 2 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-24 11:22 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-kernel, Hans Verkuil,
Mauro Carvalho Chehab, linux-media
Hi Jon,
This is a small patch series with just two patches.
The first one adds support at cdomain.py for two notations found on
Sphinx 3.1:
:c:expr:
.. c:namespace::
With that, it should now be possible to use those two C domain
tags at the media documentation, which will make it produce a
decent result with both Sphinx 1.x/2.x and Sphinx 3.1+.
The second patch manually changes the CEC documentation in
order for it to use those macros, instead of relying at the original
cdomain extensions.
I tested building the docs with both Sphinx 2.4.4 and 3.2.1.
They are identical, except by a minor difference: the output of
:c:expr: uses a bold monospaced font with 3.1+, while it uses a
non-bold monospaced font with older versions.
Yet, the output looks decent on both versions.
I'm planning to use the same approach on all the other documents
under userspace-api/media. So, I guess it would be easier if
I could merge both the cdomain.py and the media patches via
the media tree, if this is ok for you.
-
With regards to patch 1, I tried first to use a hook at 'doctree-resolved',
just like the automarkup.py, but that is too late for changing the
namespace. So, I ended hooking the extra logic at 'source-read'.
I suspect that this could be implemented on some other ways, but
this can be optimized later on, if needed.
Mauro Carvalho Chehab (2):
docs: cdomain.py: add support for two new Sphinx 3.1+ tags
media: docs: make CEC documents compatible with Sphinx 3.1+
Documentation/sphinx/cdomain.py | 56 ++++++++++++++++++-
.../media/cec/cec-func-close.rst | 7 ++-
.../media/cec/cec-func-ioctl.rst | 7 ++-
.../userspace-api/media/cec/cec-func-open.rst | 7 ++-
.../userspace-api/media/cec/cec-func-poll.rst | 11 ++--
.../media/cec/cec-ioc-adap-g-caps.rst | 9 ++-
.../media/cec/cec-ioc-adap-g-conn-info.rst | 11 ++--
.../media/cec/cec-ioc-adap-g-log-addrs.rst | 14 +++--
.../media/cec/cec-ioc-adap-g-phys-addr.rst | 14 +++--
.../media/cec/cec-ioc-dqevent.rst | 9 ++-
.../media/cec/cec-ioc-g-mode.rst | 14 +++--
.../media/cec/cec-ioc-receive.rst | 14 +++--
12 files changed, 128 insertions(+), 45 deletions(-)
--
2.26.2
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH 1/2] docs: cdomain.py: add support for two new Sphinx 3.1+ tags
2020-09-24 11:22 ` [PATCH 0/2] Start supporting builds with Sphinx 3.1+ Mauro Carvalho Chehab
@ 2020-09-24 11:22 ` Mauro Carvalho Chehab
2020-09-24 15:43 ` Jonathan Corbet
2020-09-24 11:22 ` [PATCH 2/2] media: docs: make CEC documents compatible with Sphinx 3.1+ Mauro Carvalho Chehab
1 sibling, 1 reply; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-24 11:22 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, 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 two tags:
- :c:expr:`foo`
- .. c:namespace::"
The first one just replaces the expresion by ``foo``, with
produces a monotext expression.
The second one replaces the optional "name" tag for functions,
setting a domain for all C references found after its usage.
With that, it should be possible to convert the existing
documentation to be compatible with both Sphinx 1.x/2.x and
3.1+.
Unfortunately, building the documentation with Sphinx 3.0
will produce lots of warnings, because the namespace tag
doesn't exist there, with will cause both warnings for the
usage of a non-existing tag and warnings about multiple
definitions for system calls. There's not much we can
do to solve such issues.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/cdomain.py | 56 ++++++++++++++++++++++++++++++++-
1 file changed, 55 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index cbac8e608dc4..3f6228787282 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -40,14 +40,61 @@ 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
+# - Convert :c:expr:`foo` into ``foo``
+# - Store the namespace if ".. c:namespace::" tag is found
+
+RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
+RE_expr = re.compile(r':c:expr:`([^\`]+)`')
+
+def markup_namespace(match):
+ namespace = match.group(1)
+
+ return ""
+
+def markup_c_expr(match):
+
+ return '\ ``' + match.group(1) + '``\ '
+
+def c_markups(app, docname, source):
+ result = ""
+ markup_func = {
+ RE_namespace: markup_namespace,
+ RE_expr: markup_c_expr
+ }
+
+ 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:
@@ -107,6 +154,9 @@ class CObject(Base_CObject):
param += nodes.emphasis(argname, argname)
paramlist += param
+ if namespace:
+ fullname = namespace + "." + fullname
+
return fullname
def handle_signature(self, sig, signode):
@@ -122,6 +172,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] 7+ messages in thread
* [PATCH 2/2] media: docs: make CEC documents compatible with Sphinx 3.1+
2020-09-24 11:22 ` [PATCH 0/2] Start supporting builds with Sphinx 3.1+ Mauro Carvalho Chehab
2020-09-24 11:22 ` [PATCH 1/2] docs: cdomain.py: add support for two new Sphinx 3.1+ tags Mauro Carvalho Chehab
@ 2020-09-24 11:22 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-24 11:22 UTC (permalink / raw)
To: Linux Doc Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, 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>
---
.../userspace-api/media/cec/cec-func-close.rst | 7 ++++---
.../userspace-api/media/cec/cec-func-ioctl.rst | 7 ++++---
.../userspace-api/media/cec/cec-func-open.rst | 7 ++++---
.../userspace-api/media/cec/cec-func-poll.rst | 11 ++++++-----
.../media/cec/cec-ioc-adap-g-caps.rst | 9 ++++++---
.../media/cec/cec-ioc-adap-g-conn-info.rst | 11 +++++++----
.../media/cec/cec-ioc-adap-g-log-addrs.rst | 14 +++++++++-----
.../media/cec/cec-ioc-adap-g-phys-addr.rst | 14 +++++++++-----
.../userspace-api/media/cec/cec-ioc-dqevent.rst | 9 ++++++---
.../userspace-api/media/cec/cec-ioc-g-mode.rst | 14 +++++++++-----
.../userspace-api/media/cec/cec-ioc-receive.rst | 14 +++++++++-----
11 files changed, 73 insertions(+), 44 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..7771e40aa6e8 100644
--- a/Documentation/userspace-api/media/cec/cec-func-close.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-close.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
+
.. _cec-func-close:
***********
@@ -21,13 +23,12 @@ Synopsis
.. 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
@@ -40,7 +41,7 @@ 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..3d2fed0470a8 100644
--- a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
+
.. _cec-func-ioctl:
***********
@@ -20,13 +22,12 @@ Synopsis
.. c:function:: int ioctl( int fd, int request, void *argp )
- :name: cec-ioctl
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
@@ -39,7 +40,7 @@ Arguments
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
diff --git a/Documentation/userspace-api/media/cec/cec-func-open.rst b/Documentation/userspace-api/media/cec/cec-func-open.rst
index 887bfd2a755e..de43707768ca 100644
--- a/Documentation/userspace-api/media/cec/cec-func-open.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-open.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
+
.. _cec-func-open:
**********
@@ -20,7 +22,6 @@ Synopsis
.. c:function:: int open( const char *device_name, int flags )
- :name: cec-open
Arguments
@@ -46,7 +47,7 @@ Arguments
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.
@@ -58,7 +59,7 @@ 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..3da4a96fb921 100644
--- a/Documentation/userspace-api/media/cec/cec-func-poll.rst
+++ b/Documentation/userspace-api/media/cec/cec-func-poll.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
+
.. _cec-func-poll:
**********
@@ -21,7 +23,6 @@ Synopsis
.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
- :name: cec-poll
Arguments
=========
@@ -39,10 +40,10 @@ Arguments
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 +54,13 @@ 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..f19e2e4e3f3d 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,5 +1,7 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
+
.. _CEC_ADAP_G_CAPS:
*********************
@@ -14,14 +16,15 @@ 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`` :c:expr:`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``
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..68a6dcfedfe0 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
@@ -1,7 +1,9 @@
.. SPDX-License-Identifier: GPL-2.0
..
.. Copyright 2019 Google LLC
-..
+
+.. c:namespace:: CEC
+
.. _CEC_ADAP_G_CONNECTOR_INFO:
*******************************
@@ -16,14 +18,15 @@ 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`` :c:expr:`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``
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..fafee09cd156 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,5 +1,7 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
+
.. _CEC_ADAP_LOG_ADDRS:
.. _CEC_ADAP_G_LOG_ADDRS:
.. _CEC_ADAP_S_LOG_ADDRS:
@@ -17,17 +19,19 @@ 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`` :c:expr:`ioctl(int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp)`
+
+.. c:macro:: CEC_ADAP_S_LOG_ADDRS
+
+``int`` :c:expr:`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`.
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..ba5bca26fbd8 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,5 +1,7 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
+
.. _CEC_ADAP_PHYS_ADDR:
.. _CEC_ADAP_G_PHYS_ADDR:
.. _CEC_ADAP_S_PHYS_ADDR:
@@ -17,17 +19,19 @@ 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`` :c:expr:`ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)`
+
+.. c:macro:: CEC_ADAP_S_PHYS_ADDR
+
+``int`` :c:expr:`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.
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
index 3bc81fc5a73f..394e3c3acf9d 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
+
.. _CEC_DQEVENT:
*****************
@@ -15,14 +17,15 @@ 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`` :c:expr:`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``
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..a2daf4017e91 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
+
.. _CEC_MODE:
.. _CEC_G_MODE:
.. _CEC_S_MODE:
@@ -13,17 +15,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`` :c:expr:`ioctl(int fd, CEC_G_MODE, __u32 *argp)`
+
+.. c:macro:: CEC_S_MODE
+
+``int`` :c:expr:`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.
diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
index 9d629d46973c..c0689c52e3f7 100644
--- a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
+++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. c:namespace:: CEC
+
.. _CEC_TRANSMIT:
.. _CEC_RECEIVE:
@@ -16,17 +18,19 @@ 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`` :c:expr:`ioctl(int fd, CEC_RECEIVE, struct cec_msg *argp)`
+
+.. c:macro:: CEC_TRANSMIT
+
+``int`` :c:expr:`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.
--
2.26.2
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH 1/2] docs: cdomain.py: add support for two new Sphinx 3.1+ tags
2020-09-24 11:22 ` [PATCH 1/2] docs: cdomain.py: add support for two new Sphinx 3.1+ tags Mauro Carvalho Chehab
@ 2020-09-24 15:43 ` Jonathan Corbet
2020-09-24 16:13 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 7+ messages in thread
From: Jonathan Corbet @ 2020-09-24 15:43 UTC (permalink / raw)
To: Mauro Carvalho Chehab; +Cc: Linux Doc Mailing List, linux-kernel
So I'm just getting into this and trying to understand what's really going
on, but one thing jumped at me:
On Thu, 24 Sep 2020 13:22:04 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> +# 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
> +# - Convert :c:expr:`foo` into ``foo``
> +# - Store the namespace if ".. c:namespace::" tag is found
> +
> +RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
> +RE_expr = re.compile(r':c:expr:`([^\`]+)`')
> +
> +def markup_namespace(match):
> + namespace = match.group(1)
> +
> + return ""
> +
How can this possibly work without a "global namespace" declaration in
markup_namespace()?
jon
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH 1/2] docs: cdomain.py: add support for two new Sphinx 3.1+ tags
2020-09-24 15:43 ` Jonathan Corbet
@ 2020-09-24 16:13 ` Mauro Carvalho Chehab
2020-09-24 16:22 ` Jonathan Corbet
0 siblings, 1 reply; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-24 16:13 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Linux Doc Mailing List, linux-kernel
Em Thu, 24 Sep 2020 09:43:35 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> So I'm just getting into this and trying to understand what's really going
> on, but one thing jumped at me:
>
> On Thu, 24 Sep 2020 13:22:04 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>
> > +# Namespace to be prepended to the full name
> > +namespace = None
^^^ See here....
> > +
> > +#
> > +# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags
> > +# - Convert :c:expr:`foo` into ``foo``
> > +# - Store the namespace if ".. c:namespace::" tag is found
> > +
> > +RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$')
> > +RE_expr = re.compile(r':c:expr:`([^\`]+)`')
> > +
> > +def markup_namespace(match):
> > + namespace = match.group(1)
> > +
> > + return ""
> > +
>
> How can this possibly work without a "global namespace" declaration in
> markup_namespace()?
... While I'm not a python expert, the namespace variable is global
because it was defined outside the "markup_namespace" function.
-
On a quick check at the internet, this is supposed to work properly:
https://www.programiz.com/python-programming/global-local-nonlocal-variables
-
In any cases, on my tests, this is working properly.
Anyway, I'm sending a version 2 of the series, addressing the
namespace for the remaining files under userspace-api/media.
You can try building the media books without and with the
patch series, in order to see the differences.
There are still ~200 warnings produced after that, but it
sounds that the remaining issues will require changes at
kernel-doc.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH 1/2] docs: cdomain.py: add support for two new Sphinx 3.1+ tags
2020-09-24 16:13 ` Mauro Carvalho Chehab
@ 2020-09-24 16:22 ` Jonathan Corbet
2020-09-25 4:14 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 7+ messages in thread
From: Jonathan Corbet @ 2020-09-24 16:22 UTC (permalink / raw)
To: Mauro Carvalho Chehab; +Cc: Linux Doc Mailing List, linux-kernel
On Thu, 24 Sep 2020 18:13:54 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > How can this possibly work without a "global namespace" declaration in
> > markup_namespace()?
>
> ... While I'm not a python expert, the namespace variable is global
> because it was defined outside the "markup_namespace" function.
Assignments within functions are *always* local unless declared global.
Try this:
$ python3
>>> x = 0
>>> def y(v):
>>> x = v
>>>
>>> y(1)
>>> x
0
>>>
So your assignment to "namespace" in markup_namespace() cannot change the
global, since it's not declared global.
jon
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH 1/2] docs: cdomain.py: add support for two new Sphinx 3.1+ tags
2020-09-24 16:22 ` Jonathan Corbet
@ 2020-09-25 4:14 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-09-25 4:14 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Linux Doc Mailing List, linux-kernel
Em Thu, 24 Sep 2020 10:22:25 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Thu, 24 Sep 2020 18:13:54 +0200
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>
> > > How can this possibly work without a "global namespace" declaration in
> > > markup_namespace()?
> >
> > ... While I'm not a python expert, the namespace variable is global
> > because it was defined outside the "markup_namespace" function.
>
> Assignments within functions are *always* local unless declared global.
>
> Try this:
>
> $ python3
> >>> x = 0
> >>> def y(v):
> >>> x = v
> >>>
> >>> y(1)
> >>> x
> 0
> >>>
>
> So your assignment to "namespace" in markup_namespace() cannot change the
> global, since it's not declared global.
Ok! Thanks for helping with this. I'll declare namespace as global for
the next version.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2020-09-25 4:14 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <20200924090230.6f3b0ca1@coco.lan>
2020-09-24 11:22 ` [PATCH 0/2] Start supporting builds with Sphinx 3.1+ Mauro Carvalho Chehab
2020-09-24 11:22 ` [PATCH 1/2] docs: cdomain.py: add support for two new Sphinx 3.1+ tags Mauro Carvalho Chehab
2020-09-24 15:43 ` Jonathan Corbet
2020-09-24 16:13 ` Mauro Carvalho Chehab
2020-09-24 16:22 ` Jonathan Corbet
2020-09-25 4:14 ` Mauro Carvalho Chehab
2020-09-24 11:22 ` [PATCH 2/2] media: docs: make CEC documents compatible with Sphinx 3.1+ 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).