1e8f5c617SMarkus Heiser# -*- coding: utf-8; mode: python -*- 2e8f5c617SMarkus Heiseru""" 3e8f5c617SMarkus Heiser cdomain 4e8f5c617SMarkus Heiser ~~~~~~~ 5e8f5c617SMarkus Heiser 6e8f5c617SMarkus Heiser Replacement for the sphinx c-domain. 7e8f5c617SMarkus Heiser 8e8f5c617SMarkus Heiser :copyright: Copyright (C) 2016 Markus Heiser 9e8f5c617SMarkus Heiser :license: GPL Version 2, June 1991 see Linux/COPYING for details. 102c645cd7SMarkus Heiser 112c645cd7SMarkus Heiser List of customizations: 122c645cd7SMarkus Heiser 13556aa6d5SMarkus Heiser * Moved the *duplicate C object description* warnings for function 14556aa6d5SMarkus Heiser declarations in the nitpicky mode. See Sphinx documentation for 15556aa6d5SMarkus Heiser the config values for ``nitpick`` and ``nitpick_ignore``. 16556aa6d5SMarkus Heiser 172c645cd7SMarkus Heiser * Add option 'name' to the "c:function:" directive. With option 'name' the 182c645cd7SMarkus Heiser ref-name of a function can be modified. E.g.:: 192c645cd7SMarkus Heiser 202c645cd7SMarkus Heiser .. c:function:: int ioctl( int fd, int request ) 212c645cd7SMarkus Heiser :name: VIDIOC_LOG_STATUS 222c645cd7SMarkus Heiser 232c645cd7SMarkus Heiser The func-name (e.g. ioctl) remains in the output but the ref-name changed 242c645cd7SMarkus Heiser from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by:: 252c645cd7SMarkus Heiser 262c645cd7SMarkus Heiser * :c:func:`VIDIOC_LOG_STATUS` or 272c645cd7SMarkus Heiser * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3) 28e8f5c617SMarkus Heiser""" 29e8f5c617SMarkus Heiser 302c645cd7SMarkus Heiserfrom docutils.parsers.rst import directives 312c645cd7SMarkus Heiser 32*b495360eSMarkus Heiserimport sphinx 33e8f5c617SMarkus Heiserfrom sphinx.domains.c import CObject as Base_CObject 34e8f5c617SMarkus Heiserfrom sphinx.domains.c import CDomain as Base_CDomain 35e8f5c617SMarkus Heiser 36e8f5c617SMarkus Heiser__version__ = '1.0' 37e8f5c617SMarkus Heiser 38*b495360eSMarkus Heiser# Get Sphinx version 39*b495360eSMarkus Heisermajor, minor, patch = map(int, sphinx.__version__.split(".")) 40*b495360eSMarkus Heiser 41e8f5c617SMarkus Heiserdef setup(app): 42e8f5c617SMarkus Heiser 43e8f5c617SMarkus Heiser app.override_domain(CDomain) 44e8f5c617SMarkus Heiser 45e8f5c617SMarkus Heiser return dict( 46e8f5c617SMarkus Heiser version = __version__, 47e8f5c617SMarkus Heiser parallel_read_safe = True, 48e8f5c617SMarkus Heiser parallel_write_safe = True 49e8f5c617SMarkus Heiser ) 50e8f5c617SMarkus Heiser 51e8f5c617SMarkus Heiserclass CObject(Base_CObject): 52e8f5c617SMarkus Heiser 53e8f5c617SMarkus Heiser """ 54e8f5c617SMarkus Heiser Description of a C language object. 55e8f5c617SMarkus Heiser """ 562c645cd7SMarkus Heiser option_spec = { 572c645cd7SMarkus Heiser "name" : directives.unchanged 582c645cd7SMarkus Heiser } 592c645cd7SMarkus Heiser 602c645cd7SMarkus Heiser def handle_signature(self, sig, signode): 612c645cd7SMarkus Heiser """Transform a C signature into RST nodes.""" 622c645cd7SMarkus Heiser fullname = super(CObject, self).handle_signature(sig, signode) 632c645cd7SMarkus Heiser if "name" in self.options: 642c645cd7SMarkus Heiser if self.objtype == 'function': 652c645cd7SMarkus Heiser fullname = self.options["name"] 662c645cd7SMarkus Heiser else: 672c645cd7SMarkus Heiser # FIXME: handle :name: value of other declaration types? 682c645cd7SMarkus Heiser pass 692c645cd7SMarkus Heiser return fullname 702c645cd7SMarkus Heiser 71556aa6d5SMarkus Heiser def add_target_and_index(self, name, sig, signode): 72556aa6d5SMarkus Heiser # for C API items we add a prefix since names are usually not qualified 73556aa6d5SMarkus Heiser # by a module name and so easily clash with e.g. section titles 74556aa6d5SMarkus Heiser targetname = 'c.' + name 75556aa6d5SMarkus Heiser if targetname not in self.state.document.ids: 76556aa6d5SMarkus Heiser signode['names'].append(targetname) 77556aa6d5SMarkus Heiser signode['ids'].append(targetname) 78556aa6d5SMarkus Heiser signode['first'] = (not self.names) 79556aa6d5SMarkus Heiser self.state.document.note_explicit_target(signode) 80556aa6d5SMarkus Heiser inv = self.env.domaindata['c']['objects'] 81556aa6d5SMarkus Heiser if (name in inv and self.env.config.nitpicky): 82556aa6d5SMarkus Heiser if self.objtype == 'function': 83556aa6d5SMarkus Heiser if ('c:func', name) not in self.env.config.nitpick_ignore: 84556aa6d5SMarkus Heiser self.state_machine.reporter.warning( 85556aa6d5SMarkus Heiser 'duplicate C object description of %s, ' % name + 86556aa6d5SMarkus Heiser 'other instance in ' + self.env.doc2path(inv[name][0]), 87556aa6d5SMarkus Heiser line=self.lineno) 88556aa6d5SMarkus Heiser inv[name] = (self.env.docname, self.objtype) 89556aa6d5SMarkus Heiser 90556aa6d5SMarkus Heiser indextext = self.get_index_text(name) 91556aa6d5SMarkus Heiser if indextext: 92*b495360eSMarkus Heiser if major == 1 and minor < 4: 93*b495360eSMarkus Heiser # indexnode's tuple changed in 1.4 94*b495360eSMarkus Heiser # https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c 95*b495360eSMarkus Heiser self.indexnode['entries'].append( 96*b495360eSMarkus Heiser ('single', indextext, targetname, '')) 97*b495360eSMarkus Heiser else: 98*b495360eSMarkus Heiser self.indexnode['entries'].append( 99*b495360eSMarkus Heiser ('single', indextext, targetname, '', None)) 100e8f5c617SMarkus Heiser 101e8f5c617SMarkus Heiserclass CDomain(Base_CDomain): 102e8f5c617SMarkus Heiser 103e8f5c617SMarkus Heiser """C language domain.""" 104e8f5c617SMarkus Heiser name = 'c' 105e8f5c617SMarkus Heiser label = 'C' 106e8f5c617SMarkus Heiser directives = { 107e8f5c617SMarkus Heiser 'function': CObject, 108e8f5c617SMarkus Heiser 'member': CObject, 109e8f5c617SMarkus Heiser 'macro': CObject, 110e8f5c617SMarkus Heiser 'type': CObject, 111e8f5c617SMarkus Heiser 'var': CObject, 112e8f5c617SMarkus Heiser } 113