cdomain.py 5.6 KB

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