From patchwork Fri Jun 21 23:51:57 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 167424 Delivered-To: patch@linaro.org Received: by 2002:a92:4782:0:0:0:0:0 with SMTP id e2csp1345652ilk; Fri, 21 Jun 2019 16:52:23 -0700 (PDT) X-Google-Smtp-Source: APXvYqwazM2ZhKDvDmPNBmK34DEQwuRzieepD24tGD3Esry/YlS7h6I5snl8N8i3OVnMaEZswXSY X-Received: by 2002:a17:90a:2430:: with SMTP id h45mr10225388pje.14.1561161142965; Fri, 21 Jun 2019 16:52:22 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1561161142; cv=none; d=google.com; s=arc-20160816; b=HF6dJkv751d0PT06N2RnF27iTvdz/KV1ZBg+cB63taWiX5dYUSXa0CHgTM96f3KRfQ q8OET6zpOFY7BtYJsnhyPKay1/XRU/tG9gxmzQaJ+lFIIhFHGykzEEGB5Q73p76nX/R/ 3VvcUg14qOTTXkGHhyMEs90Ic1TTAO6NFFV3l4oSosnH2qhaJ2oGqbHSomY8noOkVnUK Tv1uUZ02Pf37t7k0HlneUqQrN92XSAsz/5uSjK+5UKzRcoOBPkwwHCUZLgF36l/hsKBh +WuyfLNQGLz/Uz69yao0dfhfd4dQVaOSLLqyhcla6st2H5/8TXf9WAlPYuLHhoUYMJk4 GNtA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=RCk3u247vqI7Dz7tHVGY3kLmzIAXLLWxlNiemw8igZ0=; b=iFb8xOJLEJUUTYUOpMXkgc0QGdxqn5fq9vioN+Tp2eSHduCVp6w0cAZUfKxiohsJPa Hrk9BaTNIDxz8r2uzH0oCLOlBxHG0M2H5B07G6amGlffqRa85JJFYxn3qsT5j51bMZxd +qLS5Fkraw/ToKDIdC2uJP5EQhBsPoUUtUq6FTEzK+h2B9aHMufPOjVgYyS6YYESPwIY Vumgqyb3VnfRYkFvEGf2v8FwhYB9uzIJS6mNff+fBnCzd8AhR7LEH7k15Y3O+K7XAQ5B UfGeySAL0Z6xh4oCTeKLKrhsugZgcSx4n5C2bLuyhY1LEH027pus4YZ1/RRz6XuGGagL 1vqA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id h96si3924186plb.281.2019.06.21.16.52.22; Fri, 21 Jun 2019 16:52:22 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726212AbfFUXwO (ORCPT + 30 others); Fri, 21 Jun 2019 19:52:14 -0400 Received: from ms.lwn.net ([45.79.88.28]:55292 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726075AbfFUXwL (ORCPT ); Fri, 21 Jun 2019 19:52:11 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id D11E1536; Fri, 21 Jun 2019 23:52:10 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: Matthew Wilcox , Mauro Carvalho Chehab , Jani Nikula , linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH 1/3] Docs: An initial automarkup extension for sphinx Date: Fri, 21 Jun 2019 17:51:57 -0600 Message-Id: <20190621235159.6992-2-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190621235159.6992-1-corbet@lwn.net> References: <20190621235159.6992-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Rather than fill our text files with :c:func:`function()` syntax, just do the markup via a hook into the sphinx build process. Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 3 +- Documentation/sphinx/automarkup.py | 80 ++++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 Documentation/sphinx/automarkup.py -- 2.21.0 diff --git a/Documentation/conf.py b/Documentation/conf.py index 7ace3f8852bd..a502baecbb85 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -34,7 +34,8 @@ needs_sphinx = '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', + 'kfigure', 'sphinx.ext.ifconfig', 'automarkup'] # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1): diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py new file mode 100644 index 000000000000..14b09b5d145e --- /dev/null +++ b/Documentation/sphinx/automarkup.py @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: GPL-2.0 +# Copyright 2019 Jonathan Corbet +# +# Apply kernel-specific tweaks after the initial document processing +# has been done. +# +from docutils import nodes +from sphinx import addnodes +import re + +# +# Regex nastiness. Of course. +# Try to identify "function()" that's not already marked up some +# other way. Sphinx doesn't like a lot of stuff right after a +# :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last +# bit tries to restrict matches to things that won't create trouble. +# +RE_function = re.compile(r'([\w_][\w\d_]+\(\))') + +# +# The DVB docs create references for these basic system calls, leading +# to lots of confusing links. So just don't link them. +# +Skipfuncs = [ 'open', 'close', 'write' ] + +# +# Find all occurrences of function() and try to replace them with +# appropriate cross references. +# +def markup_funcs(docname, app, node): + cdom = app.env.domains['c'] + t = node.astext() + done = 0 + repl = [ ] + for m in RE_function.finditer(t): + # + # Include any text prior to function() as a normal text node. + # + if m.start() > done: + repl.append(nodes.Text(t[done:m.start()])) + # + # Go through the dance of getting an xref out of the C domain + # + target = m.group(1)[:-2] + target_text = nodes.Text(target + '()') + xref = None + if target not in Skipfuncs: + lit_text = nodes.literal(classes=['xref', 'c', 'c-func']) + lit_text += target_text + pxref = addnodes.pending_xref('', refdomain = 'c', + reftype = 'function', + reftarget = target, modname = None, + classname = None) + xref = cdom.resolve_xref(app.env, docname, app.builder, + 'function', target, pxref, lit_text) + # + # Toss the xref into the list if we got it; otherwise just put + # the function text. + # + if xref: + repl.append(xref) + else: + repl.append(target_text) + done = m.end() + if done < len(t): + repl.append(nodes.Text(t[done:])) + return repl + +def auto_markup(app, doctree, name): + for para in doctree.traverse(nodes.paragraph): + for node in para.traverse(nodes.Text): + if not isinstance(node.parent, nodes.literal): + node.parent.replace(node, markup_funcs(name, app, node)) + +def setup(app): + app.connect('doctree-resolved', auto_markup) + return { + 'parallel_read_safe': True, + 'parallel_write_safe': True, + }