From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-14.3 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,INCLUDES_PATCH,MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id A5A82C4727E for ; Thu, 24 Sep 2020 11:22:24 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 522642396E for ; Thu, 24 Sep 2020 11:22:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1600946543; bh=+dpjmYWc6xwsu3KtKMm2ZusLC9NPxNgjvUVnQyxzmaQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=N/IJ9yqxOCAwB62GggvcSj06N4xMUnF83PEykmUb2mOQZv05Fs4Z1eC3UOX2MfU/d GjecP0FrO/wfCQ9V+rc3SCo1WPKpfSSRo/9MliLnu1jFd/58mu0x5KvB9H0LuvzBE6 NACZOJ61FlEpswFgUwih2D7Px49CCXMitRiIAocI= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726731AbgIXLWW (ORCPT ); Thu, 24 Sep 2020 07:22:22 -0400 Received: from mail.kernel.org ([198.145.29.99]:49454 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726652AbgIXLWN (ORCPT ); Thu, 24 Sep 2020 07:22:13 -0400 Received: from mail.kernel.org (ip5f5ad5c4.dynamic.kabel-deutschland.de [95.90.213.196]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id EA7492395B; Thu, 24 Sep 2020 11:22:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1600946532; bh=+dpjmYWc6xwsu3KtKMm2ZusLC9NPxNgjvUVnQyxzmaQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=JcFWQGIq68MZzIdgA+9ANbwcshi4qO+onlXtZZBa4xrysR7ZjnPOWf+LW1m7evREE JVG4BIeYaR7gBktfQTtPfGUFJF6rAaXuPzI+94jDPEaWQ+81mKXTfPZB5aRFAi1Pyf 7MxV1Mox78Zd/TwF7BaIy2TGvFt9GlC4sYO591t8= Received: from mchehab by mail.kernel.org with local (Exim 4.94) (envelope-from ) id 1kLPKD-000AEU-H2; Thu, 24 Sep 2020 13:22:09 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH 1/2] docs: cdomain.py: add support for two new Sphinx 3.1+ tags Date: Thu, 24 Sep 2020 13:22:04 +0200 Message-Id: <4b8a20013ca0b631724e8a986544ada08ac3dfd7.1600945712.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Sender: Mauro Carvalho Chehab Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 --- 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