Commit | Line | Data |
---|---|---|
e8f5c617 MH |
1 | # -*- coding: utf-8; mode: python -*- |
2 | u""" | |
3 | cdomain | |
4 | ~~~~~~~ | |
5 | ||
6 | Replacement for the sphinx c-domain. | |
7 | ||
8 | :copyright: Copyright (C) 2016 Markus Heiser | |
9 | :license: GPL Version 2, June 1991 see Linux/COPYING for details. | |
2c645cd7 MH |
10 | |
11 | List of customizations: | |
12 | ||
556aa6d5 MH |
13 | * Moved the *duplicate C object description* warnings for function |
14 | declarations in the nitpicky mode. See Sphinx documentation for | |
15 | the config values for ``nitpick`` and ``nitpick_ignore``. | |
16 | ||
2c645cd7 MH |
17 | * Add option 'name' to the "c:function:" directive. With option 'name' the |
18 | ref-name of a function can be modified. E.g.:: | |
19 | ||
20 | .. c:function:: int ioctl( int fd, int request ) | |
21 | :name: VIDIOC_LOG_STATUS | |
22 | ||
23 | The func-name (e.g. ioctl) remains in the output but the ref-name changed | |
24 | from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by:: | |
25 | ||
26 | * :c:func:`VIDIOC_LOG_STATUS` or | |
27 | * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3) | |
e8f5c617 MH |
28 | """ |
29 | ||
2c645cd7 MH |
30 | from docutils.parsers.rst import directives |
31 | ||
e8f5c617 MH |
32 | from sphinx.domains.c import CObject as Base_CObject |
33 | from sphinx.domains.c import CDomain as Base_CDomain | |
34 | ||
35 | __version__ = '1.0' | |
36 | ||
37 | def setup(app): | |
38 | ||
39 | app.override_domain(CDomain) | |
40 | ||
41 | return dict( | |
42 | version = __version__, | |
43 | parallel_read_safe = True, | |
44 | parallel_write_safe = True | |
45 | ) | |
46 | ||
47 | class CObject(Base_CObject): | |
48 | ||
49 | """ | |
50 | Description of a C language object. | |
51 | """ | |
2c645cd7 MH |
52 | option_spec = { |
53 | "name" : directives.unchanged | |
54 | } | |
55 | ||
56 | def handle_signature(self, sig, signode): | |
57 | """Transform a C signature into RST nodes.""" | |
58 | fullname = super(CObject, self).handle_signature(sig, signode) | |
59 | if "name" in self.options: | |
60 | if self.objtype == 'function': | |
61 | fullname = self.options["name"] | |
62 | else: | |
63 | # FIXME: handle :name: value of other declaration types? | |
64 | pass | |
65 | return fullname | |
66 | ||
556aa6d5 MH |
67 | def add_target_and_index(self, name, sig, signode): |
68 | # for C API items we add a prefix since names are usually not qualified | |
69 | # by a module name and so easily clash with e.g. section titles | |
70 | targetname = 'c.' + name | |
71 | if targetname not in self.state.document.ids: | |
72 | signode['names'].append(targetname) | |
73 | signode['ids'].append(targetname) | |
74 | signode['first'] = (not self.names) | |
75 | self.state.document.note_explicit_target(signode) | |
76 | inv = self.env.domaindata['c']['objects'] | |
77 | if (name in inv and self.env.config.nitpicky): | |
78 | if self.objtype == 'function': | |
79 | if ('c:func', name) not in self.env.config.nitpick_ignore: | |
80 | self.state_machine.reporter.warning( | |
81 | 'duplicate C object description of %s, ' % name + | |
82 | 'other instance in ' + self.env.doc2path(inv[name][0]), | |
83 | line=self.lineno) | |
84 | inv[name] = (self.env.docname, self.objtype) | |
85 | ||
86 | indextext = self.get_index_text(name) | |
87 | if indextext: | |
88 | self.indexnode['entries'].append(('single', indextext, | |
89 | targetname, '', None)) | |
e8f5c617 MH |
90 | |
91 | class CDomain(Base_CDomain): | |
92 | ||
93 | """C language domain.""" | |
94 | name = 'c' | |
95 | label = 'C' | |
96 | directives = { | |
97 | 'function': CObject, | |
98 | 'member': CObject, | |
99 | 'macro': CObject, | |
100 | 'type': CObject, | |
101 | 'var': CObject, | |
102 | } |