From patchwork Tue May 21 12:25:11 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164722 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1541932ili; Tue, 21 May 2019 05:31:25 -0700 (PDT) X-Google-Smtp-Source: APXvYqwzC/EkvkzcbRmxj+RrsWIbfQSK8BdGziOVBkKD9QDu46iX+t442NRQavUR5z4s0RhbUYMr X-Received: by 2002:a17:906:3553:: with SMTP id s19mr43441404eja.204.1558441885876; Tue, 21 May 2019 05:31:25 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558441885; cv=none; d=google.com; s=arc-20160816; b=tLBcVYad0nYFMr3wgZ9q9PE+JnPgX6cqhvaiSWNf1RvaFvHzzc8xQ3fOLUoFVFDpW1 y3ZMB5/dX3xsybUocT313Y8GvVVpMbaKGcocKDWbWd1NOmbxKLAzlkHMwMOVFDcDul4T 85/XEllKQJ5Ycp6EG0mSWrbsWEP+SJfcNwEONkvzbD1xDMPGmXMo+BEZRm3lmpefoUiq 7Fo12am/1hCi4sv6BQdQMcgap2bCX5sa3psBVbLkC5nY53mcQhZfBQjOGTm3eWDfptmV pxwIv6Oi+Im8P5gR5TJiPeESjYW44CP/eqHzTHWrcneuETPctEOKTWnhU29pNOHSqbDA GXGQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=oe3qCNAnptAvVIC38GAVxc3L66obGAOTbhJyLwNyUsk=; b=ldOiPdgL1hh2aAuZgqjMOo5uCxnkFktQJjFGQenEtPL4oAM9RVqeKjF6DwtOYHiamx l6/RVsAihkob97LQ9D9Nn7NBTGe8lDzWSauVsnkveuHMXQOdoaAXoiU40KDS5sAPzgEq TUFXPkTeCzz1l6xGq+gavNHRnpKan0I53kX+z/GKk8Z3YhSz7SRAHvEu2Xp/0RTQPG8s JICEevaExAOyLe/vAmeTNR8OoSgo2l0WO+rNA1t9ULDJ/6PpunhRNcPXPx9mcFMdTFD2 NQ1YW3legc8SYG0fAcNqq5LpFZ0rsoSDNKVdwQ3YfSWp6CjVgWqWpZFzUzZ035QBvPRw cvtw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=CF4eudNm; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id l58si15779874edb.163.2019.05.21.05.31.25 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:31:25 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=CF4eudNm; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52755 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3vQ-0006vw-Cx for patch@linaro.org; Tue, 21 May 2019 08:31:24 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45328) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3q2-0001SE-QV for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:52 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3px-0005Gc-4B for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:48 -0400 Received: from mail-wm1-x341.google.com ([2a00:1450:4864:20::341]:54450) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3pw-00054z-RB for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:45 -0400 Received: by mail-wm1-x341.google.com with SMTP id i3so2779151wml.4 for ; Tue, 21 May 2019 05:25:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=oe3qCNAnptAvVIC38GAVxc3L66obGAOTbhJyLwNyUsk=; b=CF4eudNmr6WNenANAk9BDzK92mUD19XDIbKNqR4P2QmMTZGqVr/pLLjulaDg61s8lg AdgTNuLX8LSGw81aGyax7xYjb2SLTbATEWEzOTXBozCS1IwHtt1f6LCFctYzWzAHlWh4 7sCuPjaHXhlom/o7K7yTgbu72i4+MEsIL4TdMmXBQQln00mKtzABS0hSBpROLo1WTFB3 RsJ1MMfoc0uRldtvY/iNwD7e315bklA2xAIQBhCGcbiFDT26Y+m3eyKaMGcxCfEZLgHy Zoalc8X53EJEWorJ/1CtRV5ftZJVeG/F95tbi/e5PWn7ZcPueQd39da8YoMUVtSC8FJh BP3A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=oe3qCNAnptAvVIC38GAVxc3L66obGAOTbhJyLwNyUsk=; b=RpIUwOV6/BhbP1OhkkiheKtk6+5v8vt5emG7ItwLdjdduu4TTVZW/ndR6cIYgeJwXl 5IgaOiB2p6VKOeMNEQ2uOJWNRtktvPcp7pZrjrVMNu/43mfe6TZcUon2REpkCiyYTazZ R+KPAc+ILotlJVg6wV1ZsSSDwWM+1mIO04gaHAol6JC58BA6EqBAhl1OPsRXFdE+qANM sC44WISTtSMoT2CtfA3jeJoW9uRJdzhQcl3nghXGW2I/eOXoWyku7kr/Pzdog05aIAl/ huOVFrzeAqP251hIoGALrV5nMUoEfK/EvJZu+RGCcEzLTfns+ev9u2+wGRcbBwBSrHLP F6GA== X-Gm-Message-State: APjAAAVcDRcASF8HqLXWA9JuwL96R7nqkGLD17hw8c834Z+5XwBqCDYc cNgYcJYZqj6PjJmVEOgkKUuwj6Dwe+s= X-Received: by 2002:a1c:6a0e:: with SMTP id f14mr3240982wmc.69.1558441526093; Tue, 21 May 2019 05:25:26 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.24 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:25 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:11 +0100 Message-Id: <20190521122519.12573-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::341 Subject: [Qemu-devel] [RFC 02/10] docs: Add kerneldoc sphinx module from Linux X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" Add the kerneldoc sphinx module from Linux kernel commit 30bac164aca750892. Signed-off-by: Peter Maydell --- docs/sphinx/kerneldoc.py | 150 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 docs/sphinx/kerneldoc.py -- 2.20.1 diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py new file mode 100644 index 00000000000..9d0a7f08f93 --- /dev/null +++ b/docs/sphinx/kerneldoc.py @@ -0,0 +1,150 @@ +# coding=utf-8 +# +# Copyright © 2016 Intel Corporation +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. +# +# Authors: +# Jani Nikula +# +# Please make sure this works on both python2 and python3. +# + +import codecs +import os +import subprocess +import sys +import re +import glob + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from sphinx.ext.autodoc import AutodocReporter + +__version__ = '1.0' + +class KernelDocDirective(Directive): + """Extract kernel-doc comments from the specified file""" + required_argument = 1 + optional_arguments = 4 + option_spec = { + 'doc': directives.unchanged_required, + 'functions': directives.unchanged, + 'export': directives.unchanged, + 'internal': directives.unchanged, + } + has_content = False + + def run(self): + env = self.state.document.settings.env + cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + + filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] + export_file_patterns = [] + + # Tell sphinx of the dependency + env.note_dependency(os.path.abspath(filename)) + + tab_width = self.options.get('tab-width', self.state.document.settings.tab_width) + + # FIXME: make this nicer and more robust against errors + if 'export' in self.options: + cmd += ['-export'] + export_file_patterns = str(self.options.get('export')).split() + elif 'internal' in self.options: + cmd += ['-internal'] + export_file_patterns = str(self.options.get('internal')).split() + elif 'doc' in self.options: + cmd += ['-function', str(self.options.get('doc'))] + elif 'functions' in self.options: + functions = self.options.get('functions').split() + if functions: + for f in functions: + cmd += ['-function', f] + else: + cmd += ['-no-doc-sections'] + + for pattern in export_file_patterns: + for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): + env.note_dependency(os.path.abspath(f)) + cmd += ['-export-file', f] + + cmd += [filename] + + try: + env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd))) + + p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE) + out, err = p.communicate() + + out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') + + if p.returncode != 0: + sys.stderr.write(err) + + env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + elif env.config.kerneldoc_verbosity > 0: + sys.stderr.write(err) + + lines = statemachine.string2lines(out, tab_width, convert_whitespace=True) + result = ViewList() + + lineoffset = 0; + line_regex = re.compile("^#define LINENO ([0-9]+)$") + for line in lines: + match = line_regex.search(line) + if match: + # sphinx counts lines from 0 + lineoffset = int(match.group(1)) - 1 + # we must eat our comments since the upset the markup + else: + result.append(line, filename, lineoffset) + lineoffset += 1 + + node = nodes.section() + buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter) + self.state.memo.title_styles, self.state.memo.section_level = [], 0 + try: + self.state.nested_parse(result, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + + return node.children + + except Exception as e: # pylint: disable=W0703 + env.app.warn('kernel-doc \'%s\' processing failed with: %s' % + (" ".join(cmd), str(e))) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + +def setup(app): + app.add_config_value('kerneldoc_bin', None, 'env') + app.add_config_value('kerneldoc_srctree', None, 'env') + app.add_config_value('kerneldoc_verbosity', 1, 'env') + + app.add_directive('kernel-doc', KernelDocDirective) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + )