cdomain.py 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165
  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. app.override_domain(CDomain)
  36. return dict(
  37. version = __version__,
  38. parallel_read_safe = True,
  39. parallel_write_safe = True
  40. )
  41. class CObject(Base_CObject):
  42. """
  43. Description of a C language object.
  44. """
  45. option_spec = {
  46. "name" : directives.unchanged
  47. }
  48. def handle_func_like_macro(self, sig, signode):
  49. u"""Handles signatures of function-like macros.
  50. If the objtype is 'function' and the the signature ``sig`` is a
  51. function-like macro, the name of the macro is returned. Otherwise
  52. ``False`` is returned. """
  53. if not self.objtype == 'function':
  54. return False
  55. m = c_funcptr_sig_re.match(sig)
  56. if m is None:
  57. m = c_sig_re.match(sig)
  58. if m is None:
  59. raise ValueError('no match')
  60. rettype, fullname, arglist, _const = m.groups()
  61. arglist = arglist.strip()
  62. if rettype or not arglist:
  63. return False
  64. arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup
  65. arglist = [a.strip() for a in arglist.split(",")]
  66. # has the first argument a type?
  67. if len(arglist[0].split(" ")) > 1:
  68. return False
  69. # This is a function-like macro, it's arguments are typeless!
  70. signode += addnodes.desc_name(fullname, fullname)
  71. paramlist = addnodes.desc_parameterlist()
  72. signode += paramlist
  73. for argname in arglist:
  74. param = addnodes.desc_parameter('', '', noemph=True)
  75. # separate by non-breaking space in the output
  76. param += nodes.emphasis(argname, argname)
  77. paramlist += param
  78. return fullname
  79. def handle_signature(self, sig, signode):
  80. """Transform a C signature into RST nodes."""
  81. fullname = self.handle_func_like_macro(sig, signode)
  82. if not fullname:
  83. fullname = super(CObject, self).handle_signature(sig, signode)
  84. if "name" in self.options:
  85. if self.objtype == 'function':
  86. fullname = self.options["name"]
  87. else:
  88. # FIXME: handle :name: value of other declaration types?
  89. pass
  90. return fullname
  91. def add_target_and_index(self, name, sig, signode):
  92. # for C API items we add a prefix since names are usually not qualified
  93. # by a module name and so easily clash with e.g. section titles
  94. targetname = 'c.' + name
  95. if targetname not in self.state.document.ids:
  96. signode['names'].append(targetname)
  97. signode['ids'].append(targetname)
  98. signode['first'] = (not self.names)
  99. self.state.document.note_explicit_target(signode)
  100. inv = self.env.domaindata['c']['objects']
  101. if (name in inv and self.env.config.nitpicky):
  102. if self.objtype == 'function':
  103. if ('c:func', name) not in self.env.config.nitpick_ignore:
  104. self.state_machine.reporter.warning(
  105. 'duplicate C object description of %s, ' % name +
  106. 'other instance in ' + self.env.doc2path(inv[name][0]),
  107. line=self.lineno)
  108. inv[name] = (self.env.docname, self.objtype)
  109. indextext = self.get_index_text(name)
  110. if indextext:
  111. if major == 1 and minor < 4:
  112. # indexnode's tuple changed in 1.4
  113. # https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c
  114. self.indexnode['entries'].append(
  115. ('single', indextext, targetname, ''))
  116. else:
  117. self.indexnode['entries'].append(
  118. ('single', indextext, targetname, '', None))
  119. class CDomain(Base_CDomain):
  120. """C language domain."""
  121. name = 'c'
  122. label = 'C'
  123. directives = {
  124. 'function': CObject,
  125. 'member': CObject,
  126. 'macro': CObject,
  127. 'type': CObject,
  128. 'var': CObject,
  129. }