1# -*- coding: utf-8; mode: python -*-
2# pylint: disable=W0141,C0113,C0103,C0325
3u"""
4    cdomain
5    ~~~~~~~
6
7    Replacement for the sphinx c-domain.
8
9    :copyright:  Copyright (C) 2016  Markus Heiser
10    :license:    GPL Version 2, June 1991 see Linux/COPYING for details.
11
12    List of customizations:
13
14    * Moved the *duplicate C object description* warnings for function
15      declarations in the nitpicky mode. See Sphinx documentation for
16      the config values for ``nitpick`` and ``nitpick_ignore``.
17
18    * Add option 'name' to the "c:function:" directive.  With option 'name' the
19      ref-name of a function can be modified. E.g.::
20
21          .. c:function:: int ioctl( int fd, int request )
22             :name: VIDIOC_LOG_STATUS
23
24      The func-name (e.g. ioctl) remains in the output but the ref-name changed
25      from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by::
26
27          * :c:func:`VIDIOC_LOG_STATUS` or
28          * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3)
29
30     * Handle signatures of function-like macros well. Don't try to deduce
31       arguments types of function-like macros.
32
33"""
34
35from docutils import nodes
36from docutils.parsers.rst import directives
37
38import sphinx
39from sphinx import addnodes
40from sphinx.domains.c import c_funcptr_sig_re, c_sig_re
41from sphinx.domains.c import CObject as Base_CObject
42from sphinx.domains.c import CDomain as Base_CDomain
43
44__version__  = '1.0'
45
46# Get Sphinx version
47major, minor, patch = sphinx.version_info[:3]
48
49def setup(app):
50
51    if (major == 1 and minor < 8):
52        app.override_domain(CDomain)
53    else:
54        app.add_domain(CDomain, override=True)
55
56    return dict(
57        version = __version__,
58        parallel_read_safe = True,
59        parallel_write_safe = True
60    )
61
62class CObject(Base_CObject):
63
64    """
65    Description of a C language object.
66    """
67    option_spec = {
68        "name" : directives.unchanged
69    }
70
71    def handle_func_like_macro(self, sig, signode):
72        u"""Handles signatures of function-like macros.
73
74        If the objtype is 'function' and the the signature ``sig`` is a
75        function-like macro, the name of the macro is returned. Otherwise
76        ``False`` is returned.  """
77
78        if not self.objtype == 'function':
79            return False
80
81        m = c_funcptr_sig_re.match(sig)
82        if m is None:
83            m = c_sig_re.match(sig)
84            if m is None:
85                raise ValueError('no match')
86
87        rettype, fullname, arglist, _const = m.groups()
88        arglist = arglist.strip()
89        if rettype or not arglist:
90            return False
91
92        arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup
93        arglist = [a.strip() for a in arglist.split(",")]
94
95        # has the first argument a type?
96        if len(arglist[0].split(" ")) > 1:
97            return False
98
99        # This is a function-like macro, it's arguments are typeless!
100        signode  += addnodes.desc_name(fullname, fullname)
101        paramlist = addnodes.desc_parameterlist()
102        signode  += paramlist
103
104        for argname in arglist:
105            param = addnodes.desc_parameter('', '', noemph=True)
106            # separate by non-breaking space in the output
107            param += nodes.emphasis(argname, argname)
108            paramlist += param
109
110        return fullname
111
112    def handle_signature(self, sig, signode):
113        """Transform a C signature into RST nodes."""
114
115        fullname = self.handle_func_like_macro(sig, signode)
116        if not fullname:
117            fullname = super(CObject, self).handle_signature(sig, signode)
118
119        if "name" in self.options:
120            if self.objtype == 'function':
121                fullname = self.options["name"]
122            else:
123                # FIXME: handle :name: value of other declaration types?
124                pass
125        return fullname
126
127    def add_target_and_index(self, name, sig, signode):
128        # for C API items we add a prefix since names are usually not qualified
129        # by a module name and so easily clash with e.g. section titles
130        targetname = 'c.' + name
131        if targetname not in self.state.document.ids:
132            signode['names'].append(targetname)
133            signode['ids'].append(targetname)
134            signode['first'] = (not self.names)
135            self.state.document.note_explicit_target(signode)
136            inv = self.env.domaindata['c']['objects']
137            if (name in inv and self.env.config.nitpicky):
138                if self.objtype == 'function':
139                    if ('c:func', name) not in self.env.config.nitpick_ignore:
140                        self.state_machine.reporter.warning(
141                            'duplicate C object description of %s, ' % name +
142                            'other instance in ' + self.env.doc2path(inv[name][0]),
143                            line=self.lineno)
144            inv[name] = (self.env.docname, self.objtype)
145
146        indextext = self.get_index_text(name)
147        if indextext:
148            if major == 1 and minor < 4:
149                # indexnode's tuple changed in 1.4
150                # https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c
151                self.indexnode['entries'].append(
152                    ('single', indextext, targetname, ''))
153            else:
154                self.indexnode['entries'].append(
155                    ('single', indextext, targetname, '', None))
156
157class CDomain(Base_CDomain):
158
159    """C language domain."""
160    name = 'c'
161    label = 'C'
162    directives = {
163        'function': CObject,
164        'member':   CObject,
165        'macro':    CObject,
166        'type':     CObject,
167        'var':      CObject,
168    }
169