From patchwork Sat May 19 13:05:54 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luc Van Oostenryck X-Patchwork-Id: 10412843 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 0F02960353 for ; Sat, 19 May 2018 13:06:17 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id ECF1B285B6 for ; Sat, 19 May 2018 13:06:16 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id E1CCA28641; Sat, 19 May 2018 13:06:16 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.8 required=2.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI, T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 392A0285B6 for ; Sat, 19 May 2018 13:06:16 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752263AbeESNGP (ORCPT ); Sat, 19 May 2018 09:06:15 -0400 Received: from mail-wm0-f47.google.com ([74.125.82.47]:33319 "EHLO mail-wm0-f47.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752210AbeESNGN (ORCPT ); Sat, 19 May 2018 09:06:13 -0400 Received: by mail-wm0-f47.google.com with SMTP id x12-v6so6556904wmc.0 for ; Sat, 19 May 2018 06:06:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=zaInClb8p6gbbJMqAM0syAYr/adJ2hedERGiduaWU/Y=; b=ZSvoZysFIwSQPnoZKMUEH/NhQNEdIQP6OveI/lkviXJxRqrW+5CAUyZa9fAHYBzxlv XES6xeS50Z9wNiOIvU8gwHqMexrFt7kMISnGAASQARx6R5Wqc8wOonX2U5FAcEBWNLs5 Vuikl4DLie4A9gX/F4OnfRXMulY0x//1g+I/lyyG/1HctW6f6Jz6AE/seNiNFa2hvvAt jli4LUNfMcRA4MjYedswfnF5jWwoqW0RvDn8P03zPZoBupM9QTWS72O5ZZIjrKWx+mbx YLHe5B7XclvDsSDumekI9cRtZ6YJzZ8tE/mIDxWmwtPoDkw0bjvkvFWZRvnhbRHY5F68 D8bw== 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; bh=zaInClb8p6gbbJMqAM0syAYr/adJ2hedERGiduaWU/Y=; b=skyjw8ysYCQ2oppBEXXYjcLVQ8HMB7XOET1UoPUmwQt055SEW5z4HE60Nyn7JPYEBj zeBnhB2tTVMUNsCRK9ASE4QDbYZ5CrgFOn6WA2nEFHo3yU+huZofDoxKsxn55e2XucfW BN0jhPS/1JSnav09MZk8/YiQDCrCL8+AdhxZOm+B3kWWdP6DMbyGYw6tsPbTwqzNDgQZ Am/SOIObm1/UPMJnlzrVGPK6Djc+7DlZ+Te06nv26pK5cfDsbU/8GibxkAGSOnbaawdG tFgy98nf6PqfvQTZGOWVrGSYk1Om8KgC7VHh1wjjucI3jwfqF93H1KaQ1JrelMcZOSKV vlpw== X-Gm-Message-State: ALKqPwdXb2sbsxpxJkhmrVmurc+a1fo7VLFmM5dHl3w4+PUQoBuWGqAR k8jdvXvo/+83Zpbs1DP5M1sXKMHw X-Google-Smtp-Source: AB8JxZpWt5xGl2jStCQbg2k4skVa8tXErEktOofSa0qgiFijo8eL1WxzklV8aUfz1x/KnEUPoZIDzQ== X-Received: by 2002:aa7:d34e:: with SMTP id m14-v6mr4346022edr.108.1526735171785; Sat, 19 May 2018 06:06:11 -0700 (PDT) Received: from localhost.localdomain ([2a02:a03f:4039:2700:f43f:362e:7632:e7da]) by smtp.gmail.com with ESMTPSA id u2-v6sm5209915edm.0.2018.05.19.06.06.10 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 19 May 2018 06:06:11 -0700 (PDT) From: Luc Van Oostenryck To: linux-sparse@vger.kernel.org Cc: Randy Dunlap , Jani Nikula , Luc Van Oostenryck Subject: [PATCH v2 05/13] autodoc: add a sphinx c:autodoc directive for the extracted doc Date: Sat, 19 May 2018 15:05:54 +0200 Message-Id: <20180519130602.90096-6-luc.vanoostenryck@gmail.com> X-Mailer: git-send-email 2.17.0 In-Reply-To: <20180519130602.90096-1-luc.vanoostenryck@gmail.com> References: <20180519130602.90096-1-luc.vanoostenryck@gmail.com> Sender: linux-sparse-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-sparse@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Add a sphinx extension for the c:autodoc directive which will extract the doc and inject it into the document tree. This part is based on Jani Nikula's project: hawkmoth [1] which has exactly the same goal as this series but which use clang to parse the C code and extract the bloc-coments. [1] https://github.com/jnikula/hawkmoth Based-on-work-by: Jani Nikula Signed-off-by: Luc Van Oostenryck --- Documentation/conf.py | 10 +++++--- Documentation/sphinx/cdoc.py | 49 ++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 3 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 24f0f89ab..e86be1a0a 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -21,14 +21,14 @@ import datetime # -- General configuration ------------------------------------------------ -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' +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. +sys.path.insert(0, os.path.abspath('sphinx')) extensions = [ + 'cdoc' ] # support .md with python2 & python3 @@ -88,6 +88,10 @@ pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True +# -- Options for cdoc extension ------------------------------------------- + +cdoc_srcdir = '..' + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/Documentation/sphinx/cdoc.py b/Documentation/sphinx/cdoc.py index d2e569739..7137b2a67 100755 --- a/Documentation/sphinx/cdoc.py +++ b/Documentation/sphinx/cdoc.py @@ -39,6 +39,11 @@ // Some future versions will also allow to document structures, unions, // enums, typedefs and variables. // +// This documentation can be extracted into a .rst document by using +// the *autodoc* directive:: +// +// .. c:autodoc:: file.c +// """ @@ -243,4 +248,48 @@ if __name__ == '__main__': dump_doc(extract(sys.stdin, '')) + +from sphinx.ext.autodoc import AutodocReporter +import docutils +import os +class CDocDirective(docutils.parsers.rst.Directive): + required_argument = 1 + optional_arguments = 1 + has_content = False + option_spec = { + } + + def run(self): + env = self.state.document.settings.env + filename = os.path.join(env.config.cdoc_srcdir, self.arguments[0]) + env.note_dependency(os.path.abspath(filename)) + + ## create a (view) list from the extracted doc + lst = docutils.statemachine.ViewList() + f = open(filename, 'r') + for (lineno, lines) in extract(f, filename): + for l in lines.split('\n'): + lst.append(l.expandtabs(8), filename, lineno) + lineno += 1 + + ## let parse this new reST content + memo = self.state.memo + save = memo.reporter, memo.title_styles, memo.section_level + memo.reporter = AutodocReporter(lst, memo.reporter) + node = docutils.nodes.section() + try: + self.state.nested_parse(lst, 0, node, match_titles=1) + finally: + memo.reporter, memo.title_styles, memo.section_level = save + return node.children + +def setup(app): + app.add_config_value('cdoc_srcdir', None, 'env') + app.add_directive_to_domain('c', 'autodoc', CDocDirective) + + return { + 'version': __version__, + 'parallel_read_safe': True, + } + # vim: tabstop=4