summaryrefslogtreecommitdiffstats
path: root/Documentation/sphinx
diff options
context:
space:
mode:
authorMarkus Heiser <markus.heiser@darmarIT.de>2016-08-15 16:08:26 +0200
committerJonathan Corbet <corbet@lwn.net>2016-08-22 15:19:38 -0600
commit556aa6d5d9616ccfc0099c40dc239157f50ee776 (patch)
tree4df7db8dc75f1c3401446fb39ef27105f963f544 /Documentation/sphinx
parent2c645cd7c4a0d4b35da1e43ec3a5b55a64038157 (diff)
downloadlinux-556aa6d5d9616ccfc0099c40dc239157f50ee776.tar.bz2
doc-rst: moved *duplicate* warnings to nitpicky mode
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 <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/sphinx')
-rw-r--r--Documentation/sphinx/cdomain.py27
1 files changed, 27 insertions, 0 deletions
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index b1912c80ff77..9eb714ada394 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):