Markus Heiser | e8f5c617 | 2016-08-22 15:16:21 -0600 | [diff] [blame] | 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. |
Markus Heiser | 2c645cd | 2016-08-15 16:08:25 +0200 | [diff] [blame] | 10 | |
| 11 | List of customizations: |
| 12 | |
Markus Heiser | 556aa6d | 2016-08-15 16:08:26 +0200 | [diff] [blame] | 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 | |
Markus Heiser | 2c645cd | 2016-08-15 16:08:25 +0200 | [diff] [blame] | 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) |
Markus Heiser | e8f5c617 | 2016-08-22 15:16:21 -0600 | [diff] [blame] | 28 | """ |
| 29 | |
Markus Heiser | 2c645cd | 2016-08-15 16:08:25 +0200 | [diff] [blame] | 30 | from docutils.parsers.rst import directives |
| 31 | |
Markus Heiser | b495360 | 2016-09-07 09:12:56 +0200 | [diff] [blame^] | 32 | import sphinx |
Markus Heiser | e8f5c617 | 2016-08-22 15:16:21 -0600 | [diff] [blame] | 33 | from sphinx.domains.c import CObject as Base_CObject |
| 34 | from sphinx.domains.c import CDomain as Base_CDomain |
| 35 | |
| 36 | __version__ = '1.0' |
| 37 | |
Markus Heiser | b495360 | 2016-09-07 09:12:56 +0200 | [diff] [blame^] | 38 | # Get Sphinx version |
| 39 | major, minor, patch = map(int, sphinx.__version__.split(".")) |
| 40 | |
Markus Heiser | e8f5c617 | 2016-08-22 15:16:21 -0600 | [diff] [blame] | 41 | def setup(app): |
| 42 | |
| 43 | app.override_domain(CDomain) |
| 44 | |
| 45 | return dict( |
| 46 | version = __version__, |
| 47 | parallel_read_safe = True, |
| 48 | parallel_write_safe = True |
| 49 | ) |
| 50 | |
| 51 | class CObject(Base_CObject): |
| 52 | |
| 53 | """ |
| 54 | Description of a C language object. |
| 55 | """ |
Markus Heiser | 2c645cd | 2016-08-15 16:08:25 +0200 | [diff] [blame] | 56 | option_spec = { |
| 57 | "name" : directives.unchanged |
| 58 | } |
| 59 | |
| 60 | def handle_signature(self, sig, signode): |
| 61 | """Transform a C signature into RST nodes.""" |
| 62 | fullname = super(CObject, self).handle_signature(sig, signode) |
| 63 | if "name" in self.options: |
| 64 | if self.objtype == 'function': |
| 65 | fullname = self.options["name"] |
| 66 | else: |
| 67 | # FIXME: handle :name: value of other declaration types? |
| 68 | pass |
| 69 | return fullname |
| 70 | |
Markus Heiser | 556aa6d | 2016-08-15 16:08:26 +0200 | [diff] [blame] | 71 | def add_target_and_index(self, name, sig, signode): |
| 72 | # for C API items we add a prefix since names are usually not qualified |
| 73 | # by a module name and so easily clash with e.g. section titles |
| 74 | targetname = 'c.' + name |
| 75 | if targetname not in self.state.document.ids: |
| 76 | signode['names'].append(targetname) |
| 77 | signode['ids'].append(targetname) |
| 78 | signode['first'] = (not self.names) |
| 79 | self.state.document.note_explicit_target(signode) |
| 80 | inv = self.env.domaindata['c']['objects'] |
| 81 | if (name in inv and self.env.config.nitpicky): |
| 82 | if self.objtype == 'function': |
| 83 | if ('c:func', name) not in self.env.config.nitpick_ignore: |
| 84 | self.state_machine.reporter.warning( |
| 85 | 'duplicate C object description of %s, ' % name + |
| 86 | 'other instance in ' + self.env.doc2path(inv[name][0]), |
| 87 | line=self.lineno) |
| 88 | inv[name] = (self.env.docname, self.objtype) |
| 89 | |
| 90 | indextext = self.get_index_text(name) |
| 91 | if indextext: |
Markus Heiser | b495360 | 2016-09-07 09:12:56 +0200 | [diff] [blame^] | 92 | if major == 1 and minor < 4: |
| 93 | # indexnode's tuple changed in 1.4 |
| 94 | # https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c |
| 95 | self.indexnode['entries'].append( |
| 96 | ('single', indextext, targetname, '')) |
| 97 | else: |
| 98 | self.indexnode['entries'].append( |
| 99 | ('single', indextext, targetname, '', None)) |
Markus Heiser | e8f5c617 | 2016-08-22 15:16:21 -0600 | [diff] [blame] | 100 | |
| 101 | class CDomain(Base_CDomain): |
| 102 | |
| 103 | """C language domain.""" |
| 104 | name = 'c' |
| 105 | label = 'C' |
| 106 | directives = { |
| 107 | 'function': CObject, |
| 108 | 'member': CObject, |
| 109 | 'macro': CObject, |
| 110 | 'type': CObject, |
| 111 | 'var': CObject, |
| 112 | } |