Skip to content

Instantly share code, notes, and snippets.

@ssokolow

ssokolow/ocv.py

Created Apr 24, 2020
Embed
What would you like to do?
OpenCV's :ocv: Sphinx domain, patched up for Sphinx 2.3
#!/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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment