linux-kernel - [PATCH 0/2] Start supporting builds with Sphinx 3.1+

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Date:   Thu, 24 Sep 2020 13:22:03 +0200
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>
Cc:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        linux-kernel@...r.kernel.org,
        Hans Verkuil <hverkuil-cisco@...all.nl>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        linux-media@...r.kernel.org
Subject: [PATCH 0/2] Start supporting builds with Sphinx 3.1+

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