OpenCV's :ocv: Sphinx domain, patched up for Sphinx 2.3

ocv.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
    ocv domain, a modified copy of sphinx.domains.cpp + shpinx.domains.python.
                            The original copyright is below
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    The OpenCV C/C++/Python/Java/... language domain.

    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
"""

import re
from copy import deepcopy

from docutils import nodes
from docutils.parsers.rst import directives

from docutils.parsers.rst import Directive
from sphinx import addnodes
from sphinx.roles import XRefRole
from sphinx.locale import _
from sphinx.domains import Domain, ObjType
from sphinx.directives import ObjectDescription
from sphinx.util.nodes import make_refnode
from sphinx.util.docfields import Field, GroupedField, TypedField
from sphinx.util.logging import getLogger

log = getLogger(__name__)

########################### Python Part ###########################

# REs for Python signatures
py_sig_re = re.compile(
    r'''^ ([\w.]*\.)?            # class name(s)
          (\w+)  \s*             # thing name
          (?: \((.*)\)           # optional: arguments
           (?:\s* -> \s* (.*))?  #           return annotation
          )? $                   # and nothing more
          ''', re.VERBOSE)


def _pseudo_parse_arglist(signode, arglist):
    """"Parse" a list of arguments separated by commas.

    Arguments can have "optional" annotations given by enclosing them in
    brackets.  Currently, this will split at any comma, even if it's inside a
    string literal (e.g. default argument value).
    """
    paramlist = addnodes.desc_parameterlist()
    stack = [paramlist]
    try:
        for argument in arglist.split(','):
            argument = argument.strip()
            ends_open = ends_close = 0
            while argument.startswith('['):
                stack.append(addnodes.desc_optional())
                stack[-2] += stack[-1]
                argument = argument[1:].strip()
            while argument.startswith(']'):
                stack.pop()
                argument = argument[1:].strip()
            while argument.endswith(']'):
                ends_close += 1
                argument = argument[:-1].strip()
            while argument.endswith('['):
                ends_open += 1
                argument = argument[:-1].strip()
            if argument:
                stack[-1] += addnodes.desc_parameter(
                    argument, argument, noemph=True)
            while ends_open:
                stack.append(addnodes.desc_optional())
                stack[-2] += stack[-1]
                ends_open -= 1
            while ends_close:
                stack.pop()
                ends_close -= 1
        if len(stack) != 1:
            raise IndexError
    except IndexError:
        # if there are too few or too many elements on the stack, just give up
        # and treat the whole argument list as one argument, discarding the
        # already partially populated paramlist node
        signode += addnodes.desc_parameterlist()
        signode[-1] += addnodes.desc_parameter(arglist, arglist)
    else:
        signode += paramlist


class OCVPyObject(ObjectDescription):
    """
    Description of a general Python object.
    """
    option_spec = {
        'noindex': directives.flag,
        'module': directives.unchanged,
    }

    doc_field_types = [
        TypedField('parameter', label=_('Parameters'),
                   names=('param', 'parameter', 'arg', 'argument',
                          'keyword', 'kwarg', 'kwparam'),
                   typerolename='obj', typenames=('paramtype', 'type'),
                   can_collapse=True),
        TypedField('variable', label=_('Variables'), rolename='obj',
                   names=('var', 'ivar', 'cvar'),
                   typerolename='obj', typenames=('vartype',),
                   can_collapse=True),
        GroupedField('exceptions', label=_('Raises'), rolename='exc',
                     names=('raises', 'raise', 'exception', 'except'),
                     can_collapse=True),
        Field('returnvalue', label=_('Returns'), has_arg=False,
              names=('returns', 'return')),
        Field('returntype', label=_('Return type'), has_arg=False,
              names=('rtype',)),
    ]

    def get_signature_prefix(self, sig):
        """
        May return a prefix to put before the object name in the signature.
        """
        return ''

    def needs_arglist(self):
        """
        May return true if an empty argument list is to be generated even if
        the document contains none.
        """
        return False

    def handle_signature(self, sig, signode):
        """
        Transform a Python signature into RST nodes.
        Returns (fully qualified name of the thing, classname if any).

        If inside a class, the current class name is handled intelligently:
        * it is stripped from the displayed name if present
        * it is added to the full name (return value) if not present
        """
        signode += nodes.strong("Python:", "Python:")
        signode += addnodes.desc_name(" ", " ")
        m = py_sig_re.match(sig)
        if m is None:
            raise ValueError
        name_prefix, name, arglist, retann = m.groups()

        # determine module and class name (if applicable), as well as full name
        modname = self.options.get(
            'module', self.env.temp_data.get('py:module'))
        classname = self.env.temp_data.get('py:class')
        if classname:
            add_module = False
            if name_prefix and name_prefix.startswith(classname):
                fullname = name_prefix + name
                # class name is given again in the signature
                name_prefix = name_prefix[len(classname):].lstrip('.')
            elif name_prefix:
                # class name is given in the signature, but different
                # (shouldn't happen)
                fullname = classname + '.' + name_prefix + name
            else:
                # class name is not given in the signature
                fullname = classname + '.' + name
        else:
            add_module = True
            if name_prefix:
                classname = name_prefix.rstrip('.')
                fullname = name_prefix + name
            else:
                classname = ''
                fullname = name

        signode['module'] = modname
        signode['class'] = classname
        signode['fullname'] = fullname

        sig_prefix = self.get_signature_prefix(sig)
        if sig_prefix:
            signode += addnodes.desc_annotation(sig_prefix, sig_prefix)

        if name_prefix:
            signode += addnodes.desc_addname(name_prefix, name_prefix)
        # exceptions are a special case, since they are documented in the
        # 'exceptions' module.
        elif add_module and self.env.config.add_module_names:
            modname = self.options.get(
                'module', self.env.temp_data.get('py:module'))
            if modname and modname != 'exceptions':
                nodetext = modname + '.'
                signode += addnodes.desc_addname(nodetext, nodetext)

        signode += addnodes.desc_name(name, name)
        if not arglist:
            if self.needs_arglist():
                # for callables, add an empty parameter list
                signode += addnodes.desc_parameterlist()
            if retann:
                signode += addnodes.desc_returns(retann, retann)
            return fullname, name_prefix
        _pseudo_parse_arglist(signode, arglist)
        if retann:
            signode += addnodes.desc_returns(retann, retann)
        return fullname, name_prefix

    def get_index_text(self, modname, name):
        """
        Return the text for the index entry of the object.
        """
        raise NotImplementedError('must be implemented in subclasses')

    def add_target_and_index(self, name_cls, sig, signode):
        modname = self.options.get(
            'module', self.env.temp_data.get('py:module'))
        fullname = (modname and modname + '.' or '') + name_cls[0]
        # note target
        if fullname not in self.state.document.ids:
            signode['names'].append(fullname)
            signode['ids'].append(fullname)
            signode['first'] = (not self.names)
            self.state.document.note_explicit_target(signode)
            objects = self.env.domaindata['ocv']['objects']
            if fullname in objects:
                log.warning(
                    self.env.docname,
                    'duplicate object description of %s, ' % fullname +
                    'other instance in ' +
                    self.env.doc2path(objects[fullname][0]) +
                    ', use :noindex: for one of them',
                    self.lineno)
            objects.setdefault(
                fullname, (self.env.docname, self.objtype, name_cls[0]))

        indextext = self.get_index_text(modname, name_cls)
        if indextext:
            self.indexnode['entries'].append(('single', indextext,
                                              fullname, fullname))

    def before_content(self):
        # needed for automatic qualification of members (reset in subclasses)
        self.clsname_set = False

    def after_content(self):
        if self.clsname_set:
            self.env.temp_data['py:class'] = None


class OCVPyModulelevel(OCVPyObject):
    """
    Description of an object on module level (functions, data).
    """
    directive_prefix = 'py'

    def needs_arglist(self):
        return self.objtype == self.__class__.directive_prefix + 'function'

    def get_index_text(self, modname, name_cls):
        if self.objtype == self.__class__.directive_prefix + 'function':
            if not modname:
                fname = name_cls[0]
                if not fname.startswith("cv") and not fname.startswith("cv2"):
                    return _('%s() (Python function)') % fname
                pos = fname.find(".")
                modname = fname[:pos]
                fname = fname[pos + 1:]
                return _('%s() (Python function in %s)') % (fname, modname)
            return _('%s() (Python function in %s)') % (name_cls[0], modname)
        elif self.objtype == 'pydata':
            if not modname:
                return _('%s (Python variable)') % name_cls[0]
            return _('%s (in module %s)') % (name_cls[0], modname)
        else:
            return ''


class OCVPyOldModulelevel(OCVPyModulelevel):
    directive_prefix = 'pyold'
    pass


class OCVPyXRefRole(XRefRole):
    def process_link(self, env, refnode, has_explicit_title, title, target):
        refnode['ocv:module'] = env.temp_data.get('ocv:module')
        refnode['ocv:class'] = env.temp_data.get('ocv:class')
        if not has_explicit_title:
            title = title.lstrip('.')   # only has a meaning for the target
            target = target.lstrip('~')  # only has a meaning for the title
            # if the first character is a tilde, don't display the module/class
            # parts of the contents
            if title[0:1] == '~':
                title = title[1:]
                dot = title.rfind('.')
                if dot != -1:
                    title = title[dot + 1:]
        # if the first character is a dot, search more specific namespaces first
        # else search builtins first
        if target[0:1] == '.':
            target = target[1:]
            refnode['refspecific'] = True
        return title, target


########################### C/C++/Java Part ###########################

_identifier_re = re.compile(r'(~?\b[a-zA-Z_][a-zA-Z0-9_]*\b)')
_argument_name_re = re.compile(
    r'(~?\b[a-zA-Z_][a-zA-Z0-9_]*\b(?:\[\d*\])?|\.\.\.)')
_whitespace_re = re.compile(r'\s+(?u)')
_string_re = re.compile(r"[LuU8]?('([^'\\]*(?:\\.[^'\\]*)*)'"
                        r'|"([^"\\]*(?:\\.[^"\\]*)*)")', re.S)
_visibility_re = re.compile(r'\b(public|private|protected)\b')
_operator_re = re.compile(r'''(?x)
        \[\s*\]
    |   \(\s*\)
    |   (<<|>>)=?
    |   \+\+ | -- | ->\*?
    |   [!<>=/*%+|&^-]=?
    |   ~ | && | \| | \|\|
    |   \,
''')

_id_shortwords = {
    'char': 'c',
    'signed char': 'c',
    'unsigned char': 'C',
    'int': 'i',
    'signed int': 'i',
    'unsigned int': 'U',
    'long': 'l',
    'signed long': 'l',
    'unsigned long': 'L',
    'bool': 'b',
    'size_t': 's',
    'std::string': 'ss',
    'std::ostream': 'os',
    'std::istream': 'is',
    'std::iostream': 'ios',
    'std::vector': 'v',
    'std::map': 'm',
    'operator[]': 'subscript-operator',
    'operator()': 'call-operator',
    'operator!': 'not-operator',
    'operator<': 'lt-operator',
    'operator<=': 'lte-operator',
    'operator>': 'gt-operator',
    'operator>=': 'gte-operator',
    'operator=': 'assign-operator',
    'operator/': 'div-operator',
    'operator*': 'mul-operator',
    'operator%': 'mod-operator',
    'operator+': 'add-operator',
    'operator-': 'sub-operator',
    'operator|': 'or-operator',
    'operator&': 'and-operator',
    'operator^': 'xor-operator',
    'operator&&': 'sand-operator',
    'operator||': 'sor-operator',
    'operator==': 'eq-operator',
    'operator!=': 'neq-operator',
    'operator<<': 'lshift-operator',
    'operator>>': 'rshift-operator',
    'operator-=': 'sub-assign-operator',
    'operator+=': 'add-assign-operator',
    'operator*-': 'mul-assign-operator',
    'operator/=': 'div-assign-operator',
    'operator%=': 'mod-assign-operator',
    'operator&=': 'and-assign-operator',
    'operator|=': 'or-assign-operator',
    'operator<<=': 'lshift-assign-operator',
    'operator>>=': 'rshift-assign-operator',
    'operator^=': 'xor-assign-operator',
    'operator,': 'comma-operator',
    'operator->': 'pointer-operator',
    'operator->*': 'pointer-by-pointer-operator',
    'operator~': 'inv-operator',
    'operator++': 'inc-operator',
    'operator--': 'dec-operator',
    'operator new': 'new-operator',
    'operator new[]': 'new-array-operator',
    'operator delete': 'delete-operator',
    'operator delete[]': 'delete-array-operator'
}


class DefinitionError(Exception):

    def __init__(self, description):
        self.description = description

    def __unicode__(self):
        return self.description

    def __str__(self):
        return str(self.encode('utf-8'))


class DefExpr(object):

    def __unicode__(self):
        raise NotImplementedError()

    def __eq__(self, other):
        if not isinstance(self, type(other)):
            return False
        try:
            for key, value in self.__dict__.items():
                if value != getattr(other, value):
                    return False
        except AttributeError:
            return False
        return True

    def __ne__(self, other):
        return not self.__eq__(other)

    def clone(self):
        """Close a definition expression node"""
        return deepcopy(self)

    def get_id(self):
        """Returns the id for the node"""
        return ''

    def get_name(self):
        """Returns the name.  Returns either `None` or a node with
        a name you might call :meth:`split_owner` on.
        """
        return None

    def split_owner(self):
        """Nodes returned by :meth:`get_name` can split off their
        owning parent.  This function returns the owner and the
        name as a tuple of two items.  If a node does not support
        it, it returns None as owner and self as name.
        """
        return None, self

    def prefix(self, prefix):
        """Prefixes a name node (a node returned by :meth:`get_name`)."""
        raise NotImplementedError()

    def __str__(self):
        return str(self).encode('utf-8')

    def __repr__(self):
        return '<%s %s>' % (self.__class__.__name__, self)


class PrimaryDefExpr(DefExpr):

    def get_name(self):
        return self

    def prefix(self, prefix):
        if isinstance(prefix, PathDefExpr):
            prefix = prefix.clone()
            prefix.path.append(self)
            return prefix
        return PathDefExpr([prefix, self])


class NameDefExpr(PrimaryDefExpr):

    def __init__(self, name):
        self.name = name

    def get_id(self):
        name = _id_shortwords.get(self.name)
        if name is not None:
            return name
        return self.name.replace(' ', '-')

    def __unicode__(self):
        return str(self.name)


class PathDefExpr(PrimaryDefExpr):

    def __init__(self, parts):
        self.path = parts

    def get_id(self):
        rv = '::'.join(x.get_id() for x in self.path)
        return _id_shortwords.get(rv, rv)

    def split_owner(self):
        if len(self.path) > 1:
            return PathDefExpr(self.path[:-1]), self.path[-1]
        return None, self

    def prefix(self, prefix):
        if isinstance(prefix, PathDefExpr):
            prefix = prefix.clone()
            prefix.path.extend(self.path)
            return prefix
        return PathDefExpr([prefix] + self.path)

    def __unicode__(self):
        return '::'.join(map(str, self.path))


class TemplateDefExpr(PrimaryDefExpr):

    def __init__(self, typename, args):
        self.typename = typename
        self.args = args

    def split_owner(self):
        owner, typename = self.typename.split_owner()
        return owner, TemplateDefExpr(typename, self.args)

    def get_id(self):
        return '%s:%s:' % (self.typename.get_id(),
                          '.'.join(x.get_id() for x in self.args))

    def __unicode__(self):
        return '%s<%s>' % (self.typename, ', '.join(map(str, self.args)))


class WrappingDefExpr(DefExpr):

    def __init__(self, typename):
        self.typename = typename

    def get_name(self):
        return self.typename.get_name()


class ModifierDefExpr(WrappingDefExpr):

    def __init__(self, typename, modifiers):
        WrappingDefExpr.__init__(self, typename)
        self.modifiers = modifiers

    def get_id(self):
        pieces = [_id_shortwords.get(str(x), str(x))
                  for x in self.modifiers]
        pieces.append(self.typename.get_id())
        return '-'.join(pieces)

    def __unicode__(self):
        return ' '.join(map(str, list(self.modifiers) + [self.typename]))


class PtrDefExpr(WrappingDefExpr):

    def get_id(self):
        return self.typename.get_id() + 'P'

    def __unicode__(self):
        return '%s*' % self.typename


class RefDefExpr(WrappingDefExpr):

    def get_id(self):
        return self.typename.get_id() + 'R'

    def __unicode__(self):
        return '%s&' % self.typename


class ConstDefExpr(WrappingDefExpr):

    def __init__(self, typename, prefix=False):
        WrappingDefExpr.__init__(self, typename)
        self.prefix = prefix

    def get_id(self):
        return self.typename.get_id() + 'C'

    def __unicode__(self):
        return (self.prefix and 'const %s' or '%s const') % self.typename


class ConstTemplateDefExpr(WrappingDefExpr):

    def __init__(self, typename, prefix=False):
        WrappingDefExpr.__init__(self, typename)
        self.prefix = prefix

    def get_id(self):
        return self.typename.get_id() + 'C'

    def __unicode__(self):
        return (self.prefix and 'const %s' or '%s const') % self.typename


class CastOpDefExpr(PrimaryDefExpr):

    def __init__(self, typename):
        self.typename = typename

    def get_id(self):
        return 'castto-%s-operator' % self.typename.get_id()

    def __unicode__(self):
        return 'operator %s' % self.typename


class ArgumentDefExpr(DefExpr):

    def __init__(self, type, name, default=None):
        self.name = name
        self.type = type
        self.default = default

    def get_name(self):
        return self.name.get_name()

    def get_id(self):
        if self.type is None:
            return 'X'
        return self.type.get_id()

    def __unicode__(self):
        return ('%s %s' % (self.type or '', self.name or '')).strip() + \
               (self.default is not None and '=%s' % self.default or '')


class NamedDefExpr(DefExpr):

    def __init__(self, name, visibility, static):
        self.name = name
        self.visibility = visibility
        self.static = static

    def get_name(self):
        return self.name.get_name()

    def get_modifiers(self):
        rv = []
        if self.visibility != 'public':
            rv.append(self.visibility)
        if self.static:
            rv.append('static')
        return rv


class TypeObjDefExpr(NamedDefExpr):

    def __init__(self, name, visibility, static, typename):
        NamedDefExpr.__init__(self, name, visibility, static)
        self.typename = typename

    def get_id(self):
        if self.typename is None:
            return self.name.get_id()
        return '%s__%s' % (self.name.get_id(), self.typename.get_id())

    def __unicode__(self):
        buf = self.get_modifiers()
        if self.typename is None:
            buf.append(str(self.name))
        else:
            buf.extend(list(map(str, (self.typename, self.name))))
        return ' '.join(buf)


class MemberObjDefExpr(NamedDefExpr):

    def __init__(self, name, visibility, static, typename, value):
        NamedDefExpr.__init__(self, name, visibility, static)
        self.typename = typename
        self.value = value

    def get_id(self):
        return '%s__%s' % (self.name.get_id(), self.typename.get_id())

    def __unicode__(self):
        buf = self.get_modifiers()
        buf.append('%s %s' % (self.typename, self.name))
        if self.value is not None:
            buf.append('= %s' % self.value)
        return ' '.join(buf)


class FuncDefExpr(NamedDefExpr):

    def __init__(self, name, visibility, static, explicit, rv,
                 signature, const, pure_virtual, virtual):
        NamedDefExpr.__init__(self, name, visibility, static)
        self.rv = rv
        self.signature = signature
        self.explicit = explicit
        self.const = const
        self.pure_virtual = pure_virtual
        self.virtual = virtual

    def get_id(self):
        return '%s%s%s' % (
            self.name.get_id(),
            self.signature and '__' +
                '.'.join(x.get_id() for x in self.signature) or '',
            self.const and 'C' or ''
        )

    def __unicode__(self):
        buf = self.get_modifiers()
        if self.explicit:
            buf.append('explicit')
        if self.virtual:
            buf.append('virtual')
        if self.rv is not None:
            buf.append(str(self.rv))
        buf.append('%s(%s)' % (self.name, ', '.join(
            map(str, self.signature))))
        if self.const:
            buf.append('const')
        if self.pure_virtual:
            buf.append('= 0')
        return ' '.join(buf)


class ClassDefExpr(NamedDefExpr):

    def __init__(self, name, visibility, static, parents=None):
        NamedDefExpr.__init__(self, name, visibility, static)
        self.parents = parents

    def get_id(self):
        return self.name.get_id()

    def __unicode__(self):
        buf = self.get_modifiers()
        buf.append(str(self.name))
        return ' '.join(buf)


class DefinitionParser(object):

    # mapping of valid type modifiers.  if the set is None it means
    # the modifier can prefix all types, otherwise only the types
    # (actually more keywords) in the set.  Also check
    # _guess_typename when changing this.
    _modifiers = {
        'volatile': None,
        'register': None,
        'mutable': None,
        'const': None,
        'typename': None,
        'unsigned': set(('char', 'short', 'int', 'long')),
        'signed': set(('char', 'short', 'int', 'long')),
        'short': set(('int',)),
        'long': set(('int', 'long', 'double'))
    }

    def __init__(self, definition):
        self.definition = definition.strip()
        self.pos = 0
        self.end = len(self.definition)
        self.last_match = None
        self._previous_state = (0, None)

    def fail(self, msg):
        raise DefinitionError('Invalid definition: %s [error at %d]\n  %s' %
            (msg, self.pos, self.definition))

    def match(self, regex):
        match = regex.match(self.definition, self.pos)
        if match is not None:
            self._previous_state = (self.pos, self.last_match)
            self.pos = match.end()
            self.last_match = match
            return True
        return False

    def backout(self):
        self.pos, self.last_match = self._previous_state

    def skip_string(self, string):
        strlen = len(string)
        if self.definition[self.pos:self.pos + strlen] == string:
            self.pos += strlen
            return True
        return False

    def skip_word(self, word):
        return self.match(re.compile(r'\b%s\b' % re.escape(word)))

    def skip_ws(self):
        return self.match(_whitespace_re)

    @property
    def eof(self):
        return self.pos >= self.end

    @property
    def current_char(self):
        try:
            return self.definition[self.pos]
        except IndexError:
            return 'EOF'

    @property
    def matched_text(self):
        if self.last_match is not None:
            return self.last_match.group()

    def _parse_operator(self):
        self.skip_ws()
        # thank god, a regular operator definition
        if self.match(_operator_re):
            return NameDefExpr('operator' +
                              _whitespace_re.sub('', self.matched_text))
        # new/delete operator?
        for allocop in 'new', 'delete':
            if not self.skip_word(allocop):
                continue
            self.skip_ws()
            if self.skip_string('['):
                self.skip_ws()
                if not self.skip_string(']'):
                    self.fail('expected "]" for ' + allocop)
                allocop += '[]'
            return NameDefExpr('operator ' + allocop)

        # oh well, looks like a cast operator definition.
        # In that case, eat another type.
        type = self._parse_type()
        return CastOpDefExpr(type)

    def _parse_name(self):
        if not self.match(_argument_name_re):
            self.fail('expected name')
        identifier = self.matched_text

        # strictly speaking, operators are not regular identifiers
        # but because operator is a keyword, it might not be used
        # for variable names anyways, so we can safely parse the
        # operator here as identifier
        if identifier == 'operator':
            return self._parse_operator()

        return NameDefExpr(identifier)

    def _guess_typename(self, path):
        if not path:
            return [], 'int'
        # for the long type, we don't want the int in there
        if 'long' in path:
            path = [x for x in path if x != 'int']
            # remove one long
            path.remove('long')
            return path, 'long'
        if path[-1] in ('int', 'char'):
            return path[:-1], path[-1]
        return path, 'int'

    def _attach_crefptr(self, expr, is_const=False):
        if is_const:
            expr = ConstDefExpr(expr, prefix=True)
        while True:
            self.skip_ws()
            if self.skip_word('const'):
                expr = ConstDefExpr(expr)
            elif self.skip_string('*'):
                expr = PtrDefExpr(expr)
            elif self.skip_string('&'):
                expr = RefDefExpr(expr)
            else:
                return expr

    def _peek_const(self, path):
        try:
            path.remove('const')
            return True
        except ValueError:
            return False

    def _parse_builtin(self, modifier):
        path = [modifier]
        following = self._modifiers[modifier]
        while True:
            self.skip_ws()
            if not self.match(_identifier_re):
                break
            identifier = self.matched_text
            if identifier in following:
                path.append(identifier)
                following = self._modifiers[modifier]
                assert following
            else:
                self.backout()
                break

        is_const = self._peek_const(path)
        modifiers, typename = self._guess_typename(path)
        rv = ModifierDefExpr(NameDefExpr(typename), modifiers)
        return self._attach_crefptr(rv, is_const)

    def _parse_type_expr(self):
        typename = self._parse_name()
        if typename and self.skip_string('['):
            typename.name += '['
            if self.match(re.compile(r'\d*')):
                typename.name += self.last_match.group(0)
            typename.name += ']'
            if not self.skip_string(']'):
                self.fail('expected type')
        self.skip_ws()
        if not self.skip_string('<'):
            return typename

        args = []
        while True:
            self.skip_ws()
            if self.skip_string('>'):
                break
            if args:
                if not self.skip_string(','):
                    self.fail('"," or ">" in template expected')
                self.skip_ws()
            args.append(self._parse_type(True))
        return TemplateDefExpr(typename, args)

    def _parse_type(self, in_template=False):
        self.skip_ws()
        result = []
        modifiers = []

        if self.match(re.compile(r'template\w*<([^>]*)>')):
            args = self.last_match.group(1).split(',')
            args = [a.strip() for a in args]
            modifiers.append(TemplateDefExpr('template', args))

        # if there is a leading :: or not, we don't care because we
        # treat them exactly the same.  Buf *if* there is one, we
        # don't have to check for type modifiers
        if not self.skip_string('::'):
            self.skip_ws()
            while self.match(_identifier_re):
                modifier = self.matched_text
                if modifier in self._modifiers:
                    following = self._modifiers[modifier]
                    # if the set is not none, there is a limited set
                    # of types that might follow.  It is technically
                    # impossible for a template to follow, so what
                    # we do is go to a different function that just
                    # eats types
                    if following is not None:
                        return self._parse_builtin(modifier)
                    modifiers.append(modifier)
                else:
                    self.backout()
                    break

        while True:
            self.skip_ws()
            if (in_template and self.current_char in ',>') or \
               (result and not self.skip_string('::')) or \
               self.eof:
                break
            result.append(self._parse_type_expr())

        if not result:
            self.fail('expected type')
        if len(result) == 1:
            rv = result[0]
        else:
            rv = PathDefExpr(result)
        is_const = self._peek_const(modifiers)
        if is_const:
            rv = ConstDefExpr(rv, prefix=True)
        if modifiers:
            rv = ModifierDefExpr(rv, modifiers)
        return self._attach_crefptr(rv, False)

    def _parse_default_expr(self):
        self.skip_ws()
        if self.match(_string_re):
            return self.matched_text
        paren_stack_depth = 0
        max_pos = len(self.definition)
        rv_start = self.pos
        while True:
            idx0 = self.definition.find('(', self.pos)
            idx1 = self.definition.find(',', self.pos)
            idx2 = self.definition.find(')', self.pos)
            if idx0 < 0:
                idx0 = max_pos
            if idx1 < 0:
                idx1 = max_pos
            if idx2 < 0:
                idx2 = max_pos
            idx = min(idx0, idx1, idx2)
            if idx >= max_pos:
                self.fail('unexpected end in default expression')
            if idx == idx0:
                paren_stack_depth += 1
            elif idx == idx2:
                paren_stack_depth -= 1
                if paren_stack_depth < 0:
                    break
            elif paren_stack_depth == 0:
                break
            self.pos = idx + 1

        rv = self.definition[rv_start:idx]
        self.pos = idx
        return rv

    def _parse_signature(self):
        if r'CvStatModel::train' in self.definition:
            # hack to skip parsing of problematic definition
            self.pos = self.end
            return [ArgumentDefExpr("const Mat&", "train_data", None), ArgumentDefExpr(None, self.definition[self.definition.find("["):-1], None)], False, True

        self.skip_ws()
        if not self.skip_string('('):
            self.fail('expected parentheses for function')

        args = []
        while True:
            self.skip_ws()
            if self.eof:
                self.fail('missing closing parentheses')
            if self.skip_string(')'):
                break
            if args:
                if not self.skip_string(','):
                    self.fail('expected comma between arguments')
                self.skip_ws()

            argtype = self._parse_type()
            self.skip_ws()
            if str(argtype) == "...":
                if not self.skip_string(')'):
                    self.fail("var arg must be the last argument")
                args.append(ArgumentDefExpr(None, argtype, None))
                break
            argname = default = None
            if self.skip_string('='):
                self.pos += 1
                default = self._parse_default_expr()
            elif self.current_char not in ',)':
                argname = self._parse_name()
                self.skip_ws()
                if self.skip_string('='):
                    default = self._parse_default_expr()

            args.append(ArgumentDefExpr(argtype, argname, default))
        self.skip_ws()
        const = self.skip_word('const')
        if const:
            self.skip_ws()
        if self.skip_string('='):
            self.skip_ws()
            if not (self.skip_string('0') or
                    self.skip_word('NULL') or
                    self.skip_word('nullptr')):
                self.fail('pure virtual functions must be defined with '
                          'either 0, NULL or nullptr, other macros are '
                          'not allowed')
            pure_virtual = True
        else:
            pure_virtual = False
        return args, const, pure_virtual

    def _parse_visibility_static(self):
        visibility = 'public'
        if self.match(_visibility_re):
            visibility = self.matched_text
        static = self.skip_word('static')
        return visibility, static

    def parse_type(self):
        return self._parse_type()

    def parse_type_object(self):
        visibility, static = self._parse_visibility_static()
        typename = self._parse_type()
        self.skip_ws()
        if not self.eof:
            name = self._parse_type()
        else:
            name = typename
            typename = None
        return TypeObjDefExpr(name, visibility, static, typename)

    def parse_member_object(self):
        visibility, static = self._parse_visibility_static()
        typename = self._parse_type()
        name = self._parse_type()
        self.skip_ws()
        if self.skip_string('='):
            value = self.read_rest().strip()
        else:
            value = None
        return MemberObjDefExpr(name, visibility, static, typename, value)

    def parse_enum_member_object(self):
        visibility, static = self._parse_visibility_static()
        typename = None
        name = self._parse_type()
        self.skip_ws()
        if self.skip_string('='):
            value = self.read_rest().strip()
        else:
            value = None
        return MemberObjDefExpr(name, visibility, static, typename, value)

    def parse_function(self):
        visibility, static = self._parse_visibility_static()
        if self.skip_word('explicit'):
            explicit = True
            self.skip_ws()
        else:
            explicit = False
        if self.skip_word('virtual'):
            virtual = True
            self.skip_ws()
        else:
            virtual = False
        rv = self._parse_type()
        self.skip_ws()
        # some things just don't have return values
        if self.current_char == '(':
            name = rv
            rv = None
        else:
            name = self._parse_type()
        return FuncDefExpr(name, visibility, static, explicit, rv,
                           *self._parse_signature(), virtual=virtual)

    def parse_class(self):
        visibility, static = self._parse_visibility_static()
        typename = self._parse_type()
        parent = None
        self.skip_ws()
        parents = []
        if self.skip_string(':'):
            while not self.eof:
                self.skip_ws()
                classname_pos = self.pos
                pvisibility, pstatic = self._parse_visibility_static()
                if pstatic:
                    self.fail('unsepected static keyword, got %r' %
                          self.definition[self.classname_pos:])
                parents.append(
                    ClassDefExpr(self._parse_type(), pvisibility, pstatic))
                if not self.skip_string(','):
                    break
        return ClassDefExpr(typename, visibility, static, parents)

    def read_rest(self):
        rv = self.definition[self.pos:]
        self.pos = self.end
        return rv

    def assert_end(self):
        self.skip_ws()
        if not self.eof:
            self.fail('expected end of definition, got %r' %
                      self.definition[self.pos:])


class OCVObject(ObjectDescription):
    """Description of a C++ language object."""

    langname = "C++"
    ismember = False

    doc_field_types = [
        TypedField('parameter', label=_('Parameters'),
                   names=('param', 'parameter', 'arg', 'argument'),
                   typerolename='type', typenames=('type',)),
        Field('returnvalue', label=_('Returns'), has_arg=False,
              names=('returns', 'return')),
        Field('returntype', label=_('Return type'), has_arg=False,
              names=('rtype',)),
    ]

    def attach_name(self, node, name):
        owner, name = name.split_owner()
        varname = str(name)
        if owner is not None:
            owner = str(owner) + '::'
            node += addnodes.desc_addname(owner, owner)
        node += addnodes.desc_name(varname, varname)

    def attach_type(self, node, type):
        # XXX: link to c?
        text = str(type)
        pnode = addnodes.pending_xref(
            '', refdomain='ocv', reftype='type',
            reftarget=text, modname=None, classname=None)
        pnode['ocv:parent'] = self.env.temp_data.get('ocv:parent')
        pnode += nodes.Text(text)
        node += pnode

    def attach_modifiers(self, node, obj):
        if not self.__class__.ismember:
            lname = self.__class__.langname
            node += nodes.strong(lname + ":", lname + ":")
            node += addnodes.desc_name(" ", " ")

        if obj.visibility != 'public':
            node += addnodes.desc_annotation(obj.visibility,
                                             obj.visibility)
            node += nodes.Text(' ')
        if obj.static:
            node += addnodes.desc_annotation('static', 'static')
            node += nodes.Text(' ')

    def add_target_and_index(self, sigobj, sig, signode):
        theid = sig  # obj.get_id()
        theid = re.sub(r" +", " ", theid)
        if self.objtype == 'emember':
            theid = re.sub(r" ?=.*", "", theid)
        theid = re.sub(r"=[^,()]+\([^)]*?\)[^,)]*(,|\))", "\\1", theid)
        theid = re.sub(r"=\w*[^,)(]+(,|\))", "\\1", theid)
        theid = theid.replace("( ", "(").replace(" )", ")")
        name = str(sigobj.name)
        if theid not in self.state.document.ids:
            signode['names'].append(theid)
            signode['ids'].append(theid)
            signode['first'] = (not self.names)
            self.state.document.note_explicit_target(signode)

            #self.env.domaindata['ocv']['objects'].setdefault(name,
                #(self.env.docname, self.objtype, theid))
            self.env.domaindata['ocv']['objects'].setdefault(theid,
                (self.env.docname, self.objtype, theid))
            self.env.domaindata['ocv']['objects2'].setdefault(name,
                (self.env.docname, self.objtype, theid))

        indextext = self.get_index_text(name)
        if indextext:
            self.indexnode['entries'].append(
                ('single', indextext, theid, name))

    def before_content(self):
        lastname = self.names and self.names[-1]
        if lastname and not self.env.temp_data.get('ocv:parent'):
            assert isinstance(lastname, NamedDefExpr)
            self.env.temp_data['ocv:parent'] = lastname.name
            self.parentname_set = True
        else:
            self.parentname_set = False

    def after_content(self):
        if self.parentname_set:
            self.env.temp_data['ocv:parent'] = None

    def parse_definition(self, parser):
        raise NotImplementedError()

    def describe_signature(self, signode, arg):
        raise NotImplementedError()

    def handle_signature(self, sig, signode):
        parser = DefinitionParser(sig)
        try:
            rv = self.parse_definition(parser)
            parser.assert_end()
        except DefinitionError as e:
            log.warning(self.env.docname,
                        e.description, self.lineno)
            raise ValueError
        self.describe_signature(signode, rv)

        parent = self.env.temp_data.get('ocv:parent')
        if parent is not None:
            rv = rv.clone()
            rv.name = rv.name.prefix(parent)
        return rv


class OCVClassObject(OCVObject):
    object_annotation = "class "
    object_long_name = "class"

    def attach_modifiers(self, node, obj, skip_visibility='public'):
        if obj.visibility != skip_visibility:
            node += addnodes.desc_annotation(obj.visibility,
                                             obj.visibility)
            node += nodes.Text(' ')
        if obj.static:
            node += addnodes.desc_annotation('static', 'static')
            node += nodes.Text(' ')

    def get_index_text(self, name):
        return _('%s (C++ %s)') % (name, self.__class__.object_long_name)

    def parse_definition(self, parser):
        return parser.parse_class()

    def describe_signature(self, signode, cls):
        self.attach_modifiers(signode, cls)
        signode += addnodes.desc_annotation(
            self.__class__.object_annotation, self.__class__.object_annotation)
        self.attach_name(signode, cls.name)
        first_parent = True
        for p in cls.parents:
            if first_parent:
                signode += nodes.Text(' : ')
                first_parent = False
            else:
                signode += nodes.Text(', ')
            self.attach_modifiers(signode, p, None)
            self.attach_name(signode, p.name)


class OCVStructObject(OCVClassObject):
    object_annotation = "struct "
    object_long_name = "structure"


class OCVTypeObject(OCVObject):

    def get_index_text(self, name):
        if self.objtype == 'type':
            return _('%s (C++ type)') % name
        return ''

    def parse_definition(self, parser):
        return parser.parse_type_object()

    def describe_signature(self, signode, obj):
        self.attach_modifiers(signode, obj)
        signode += addnodes.desc_annotation('type ', 'type ')
        if obj.typename is not None:
            self.attach_type(signode, obj.typename)
            signode += nodes.Text(' ')
        self.attach_name(signode, obj.name)


class OCVEnumObject(OCVObject):

    def get_index_text(self, name):
        if self.objtype == 'enum':
            return _('%s (enum)') % name
        return ''

    def parse_definition(self, parser):
        return parser.parse_type_object()

    def describe_signature(self, signode, obj):
        self.attach_modifiers(signode, obj)
        signode += addnodes.desc_annotation('enum ', 'enum ')
        if obj.typename is not None:
            self.attach_type(signode, obj.typename)
            signode += nodes.Text(' ')
        self.attach_name(signode, obj.name)


class OCVMemberObject(OCVObject):
    ismember = True

    def get_index_text(self, name):
        if self.objtype == 'member':
            return _('%s (C++ member)') % name
        return ''

    def parse_definition(self, parser):
        parent_class = self.env.temp_data.get('ocv:parent')
        if parent_class is None:
            parser.fail("missing parent structure/class")
        return parser.parse_member_object()

    def describe_signature(self, signode, obj):
        self.attach_modifiers(signode, obj)
        if obj.typename:
            self.attach_type(signode, obj.typename)
            signode += nodes.Text(' ')
        self.attach_name(signode, obj.name)
        if obj.value is not None:
            signode += nodes.Text(' = ' + obj.value)


class OCVEnumMemberObject(OCVMemberObject):
    def parse_definition(self, parser):
        # parent_class = self.env.temp_data.get('ocv:parent')
        # if parent_class is None:
        #     parser.fail("missing parent structure/class")
        return parser.parse_enum_member_object()


class OCVFunctionObject(OCVObject):

    def attach_function(self, node, func):
        owner, name = func.name.split_owner()
        if owner is not None:
            owner = str(owner) + '::'
            node += addnodes.desc_addname(owner, owner)

        # cast operator is special.  in this case the return value
        # is reversed.
        if isinstance(name, CastOpDefExpr):
            node += addnodes.desc_name('operator', 'operator')
            node += nodes.Text(' ')
            self.attach_type(node, name.typename)
        else:
            funcname = str(name)
            node += addnodes.desc_name(funcname, funcname)

        paramlist = addnodes.desc_parameterlist()
        for arg in func.signature:
            param = addnodes.desc_parameter('', '', noemph=True)
            if arg.type is not None:
                self.attach_type(param, arg.type)
                param += nodes.Text(' ')
            #param += nodes.emphasis(unicode(arg.name), unicode(arg.name))
            sbrIdx = str(arg.name).find("[")
            if sbrIdx < 0:
                param += nodes.strong(str(arg.name), str(arg.name))
            else:
                param += nodes.strong(
                    str(arg.name)[:sbrIdx], str(arg.name)[:sbrIdx])
                param += nodes.Text(str(arg.name)[sbrIdx:])
            if arg.default is not None:
                def_ = '=' + str(arg.default)
                #param += nodes.emphasis(def_, def_)
                param += nodes.Text(def_)
            paramlist += param

        node += paramlist
        if func.const:
            node += addnodes.desc_addname(' const', ' const')
        if func.pure_virtual:
            node += addnodes.desc_addname(' = 0', ' = 0')

    def get_index_text(self, name):
        lname = self.__class__.langname
        if lname == "C" and name.startswith("cv"):
            name = name[2:]
        return _('%s (%s function)') % (name, lname)

    def parse_definition(self, parser):
        return parser.parse_function()

    def describe_signature(self, signode, func):
        self.attach_modifiers(signode, func)
        if func.explicit:
            signode += addnodes.desc_annotation('explicit', 'explicit')
            signode += nodes.Text(' ')
        if func.virtual:
            signode += addnodes.desc_annotation('virtual', 'virtual')
            signode += nodes.Text(' ')
        # return value is None for things with a reverse return value
        # such as casting operator definitions or constructors
        # and destructors.
        if func.rv is not None:
            self.attach_type(signode, func.rv)
        signode += nodes.Text(' ')
        self.attach_function(signode, func)


class OCVCurrentNamespace(Directive):
    """This directive is just to tell Sphinx that we're documenting
    stuff in namespace foo.
    """

    has_content = False
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {}

    def run(self):
        env = self.state.document.settings.env
        if self.arguments[0].strip() in ('NULL', '0', 'nullptr'):
            env.temp_data['ocv:prefix'] = None
        else:
            parser = DefinitionParser(self.arguments[0])
            try:
                prefix = parser.parse_type()
                parser.assert_end()
            except DefinitionError as e:
                log.warning(self.env.docname,
                            e.description, self.lineno)
            else:
                env.temp_data['ocv:prefix'] = prefix
        return []


class OCVXRefRole(XRefRole):

    def process_link(self, env, refnode, has_explicit_title, title, target):
        refnode['ocv:parent'] = env.temp_data.get('ocv:parent')
        if not has_explicit_title:
            target = target.lstrip('~')  # only has a meaning for the title
            # if the first character is a tilde, don't display the module/class
            # parts of the contents
            if title[:1] == '~':
                title = title[1:]
                dcolon = title.rfind('::')
                if dcolon != -1:
                    title = title[dcolon + 2:]
        return title, target


class OCVCFunctionObject(OCVFunctionObject):
    langname = "C"


class OCVJavaFunctionObject(OCVFunctionObject):
    langname = "Java"


class OCVDomain(Domain):
    """OpenCV C++ language domain."""
    name = 'ocv'
    label = 'C++'
    object_types = {
        'class': ObjType(_('class'), 'class'),
        'struct': ObjType(_('struct'), 'struct'),
        'function': ObjType(_('function'), 'func', 'funcx'),
        'cfunction': ObjType(_('cfunction'), 'cfunc', 'cfuncx'),
        'jfunction': ObjType(_('jfunction'), 'jfunc', 'jfuncx'),
        'pyfunction': ObjType(_('pyfunction'), 'pyfunc'),
        'pyoldfunction': ObjType(_('pyoldfunction'), 'pyoldfunc'),
        'member': ObjType(_('member'), 'member'),
        'emember': ObjType(_('emember'), 'emember'),
        'type': ObjType(_('type'), 'type'),
        'enum': ObjType(_('enum'), 'enum')
    }

    directives = {
        'class': OCVClassObject,
        'struct': OCVStructObject,
        'function': OCVFunctionObject,
        'cfunction': OCVCFunctionObject,
        'jfunction': OCVJavaFunctionObject,
        'pyfunction': OCVPyModulelevel,
        'pyoldfunction': OCVPyOldModulelevel,
        'member': OCVMemberObject,
        'emember': OCVEnumMemberObject,
        'type': OCVTypeObject,
        'enum': OCVEnumObject,
        'namespace': OCVCurrentNamespace
    }
    roles = {
        'class': OCVXRefRole(),
        'struct': OCVXRefRole(),
        'func': OCVXRefRole(fix_parens=True),
        'funcx': OCVXRefRole(),
        'cfunc': OCVXRefRole(fix_parens=True),
        'cfuncx': OCVXRefRole(),
        'jfunc': OCVXRefRole(fix_parens=True),
        'jfuncx': OCVXRefRole(),
        'pyfunc': OCVPyXRefRole(),
        'pyoldfunc': OCVPyXRefRole(),
        'member': OCVXRefRole(),
        'emember': OCVXRefRole(),
        'type': OCVXRefRole(),
        'enum': OCVXRefRole()
    }
    initial_data = {
        'objects': {},  # fullname -> docname, objtype
    }

    def __init__(self, env):
        Domain.__init__(self, env)
        self.data['objects2'] = {}

    def clear_doc(self, docname):
        for fullname, (fn, _, _) in list(self.data['objects'].items()):
            if fn == docname:
                del self.data['objects'][fullname]

    def resolve_xref(self, env, fromdocname, builder,
                     typ, target, node, contnode):
        def _create_refnode(expr):
            name = str(expr)
            if "type" in self.objtypes_for_role(typ):
                return None
            if "cfunction" in self.objtypes_for_role(typ):
                if not name.startswith('cv'):
                    name = 'cv' + name
            dict = self.data['objects']
            if name not in dict:
                dict = self.data['objects2']
            if name not in dict:
                refdoc = node.get('refdoc', fromdocname)
                log.warning(refdoc, 'unresolved reference: %r - %r' %
                            (target, typ), node.line)
                return None
            obj = dict[name]
            if obj[1] not in self.objtypes_for_role(typ):
                return None
            title = obj[2]
            if "class" in self.objtypes_for_role(typ):
                title = "class " + title
            elif "struct" in self.objtypes_for_role(typ):
                title = "struct " + title
            return make_refnode(builder, fromdocname, obj[0], obj[2],
                                contnode, title)

        parser = DefinitionParser(target)
        try:
            expr = parser.parse_type().get_name()
            parser.skip_ws()
            if not parser.eof or expr is None:
                raise DefinitionError('')
        except DefinitionError:
            refdoc = node.get('refdoc', fromdocname)
            #log.warning(refdoc, 'unparseable C++ definition: %r' % target,
            #            node.line)
            return None

        parent = node['ocv:parent']

        rv = _create_refnode(expr)
        if rv is not None or parent is None:
            return rv
        parent = parent.get_name()

        rv = _create_refnode(expr.prefix(parent))
        if rv is not None:
            return rv

        parent, name = parent.split_owner()
        return _create_refnode(expr.prefix(parent))

    def get_objects(self):
        for refname, (docname, type, theid) in self.data['objects'].items():
            yield (refname, refname, type, docname, refname, 1)

    def get_type_name(self, type, primary=False):
        """
        Return full name for given ObjType.
        """
        if primary:
            return type.lname

        return {
            'class': _('C++ class'),
            'struct': _('C/C++ struct'),
            'function': _('C++ function'),
            'cfunction': _('C function'),
            'jfunction': _('Java method'),
            'pyfunction': _('Python function'),
            'pyoldfunction': _('Legacy Python function'),
            'member': _('C++ member'),
            'emember': _('enum member'),
            'type': _('C/C++ type'),
            'enum': _('C/C++ enum'),
            'namespace': _('C++ namespace'),
        }.get(type.lname, _('%s %s') % (self.label, type.lname))


def setup(app):
    app.add_domain(OCVDomain)