Documentation/sphinx/cdomain.py

   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.
  10
  11     List of customizations:
  12
  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
  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)
  28 """
  29
  30 from docutils.parsers.rst import directives
  31
  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     """
  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
  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))
  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     }