From patchwork Mon Aug 15 14:08:26 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Heiser X-Patchwork-Id: 9281033 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 1021960467 for ; Mon, 15 Aug 2016 14:10:38 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 01DE428C40 for ; Mon, 15 Aug 2016 14:10:38 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id EA79928CA0; Mon, 15 Aug 2016 14:10:37 +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=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI 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 548E228C40 for ; Mon, 15 Aug 2016 14:10:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752927AbcHOOKF (ORCPT ); Mon, 15 Aug 2016 10:10:05 -0400 Received: from smtp1.goneo.de ([85.220.129.30]:33610 "EHLO smtp1.goneo.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753192AbcHOOI5 (ORCPT ); Mon, 15 Aug 2016 10:08:57 -0400 Received: from localhost (localhost [127.0.0.1]) by smtp1.goneo.de (Postfix) with ESMTP id 2F718241D84; Mon, 15 Aug 2016 16:08:50 +0200 (CEST) X-Virus-Scanned: by goneo Received: from smtp1.goneo.de ([127.0.0.1]) by localhost (smtp1.goneo.de [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id u3CbYqT9NN-D; Mon, 15 Aug 2016 16:08:39 +0200 (CEST) Received: from ubu1604.fritz.box (dyndsl-095-033-002-186.ewe-ip-backbone.de [95.33.2.186]) by smtp1.goneo.de (Postfix) with ESMTPSA id 82B7E2425D8; Mon, 15 Aug 2016 16:08:39 +0200 (CEST) From: Markus Heiser To: Jonathan Corbet , Mauro Carvalho Chehab , Jani Nikula Cc: Markus Heiser , Linux Media Mailing List , linux-doc@vger.kernel.org Subject: [PATCH 3/5] doc-rst: moved *duplicate* warnings to nitpicky mode Date: Mon, 15 Aug 2016 16:08:26 +0200 Message-Id: <1471270108-29314-4-git-send-email-markus.heiser@darmarit.de> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1471270108-29314-1-git-send-email-markus.heiser@darmarit.de> References: <1471270108-29314-1-git-send-email-markus.heiser@darmarit.de> Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Markus Heiser Moved the *duplicate C object description* warnings for function declarations in the nitpicky mode. In nitpick mode, you can suppress those warnings (e.g. ioctl) with:: nitpicky = True nitpick_ignore = [ ("c:func", "ioctl"), ] See Sphinx documentation for the config values for ``nitpick`` and ``nitpick_ignore`` [1]. With this change all the ".. cpp:function:: int ioctl(..)" descriptions (found in the media book) can be migrated to ".. c:function:: int ioctl(..)", without getting any warnings. E.g.:: .. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp ) .. c:function:: int ioctl( int fd, int request, struct cec_event *argp ) The main effect, is that we get those *CPP-types* back into Sphinx's C- namespace and we need no longer to distinguish between c/cpp references, when we refer a function like the ioctl. [1] http://www.sphinx-doc.org/en/stable/config.html?highlight=nitpick#confval-nitpicky Signed-off-by: Markus Heiser --- Documentation/sphinx/cdomain.py | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index 99cd035..cb4e8c9 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -10,6 +10,10 @@ u""" List of customizations: + * Moved the *duplicate C object description* warnings for function + declarations in the nitpicky mode. See Sphinx documentation for + the config values for ``nitpick`` and ``nitpick_ignore``. + * Add option 'name' to the "c:function:" directive. With option 'name' the ref-name of a function can be modified. E.g.:: @@ -60,6 +64,29 @@ class CObject(Base_CObject): pass return fullname + def add_target_and_index(self, name, sig, signode): + # for C API items we add a prefix since names are usually not qualified + # by a module name and so easily clash with e.g. section titles + targetname = 'c.' + name + if targetname not in self.state.document.ids: + signode['names'].append(targetname) + signode['ids'].append(targetname) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + inv = self.env.domaindata['c']['objects'] + if (name in inv and self.env.config.nitpicky): + if self.objtype == 'function': + if ('c:func', name) not in self.env.config.nitpick_ignore: + self.state_machine.reporter.warning( + 'duplicate C object description of %s, ' % name + + 'other instance in ' + self.env.doc2path(inv[name][0]), + line=self.lineno) + inv[name] = (self.env.docname, self.objtype) + + indextext = self.get_index_text(name) + if indextext: + self.indexnode['entries'].append(('single', indextext, + targetname, '', None)) class CDomain(Base_CDomain):