def __init__(self, name, names=(), typenames=(), label=None,
rolename=None, typerolename=None,
shapenames=None, attrnames=None,
prefix=None,
strong=True,
can_collapse=False):
GroupedField.__init__(self, name, names, label, rolename, can_collapse)
self.typenames = typenames
self.typerolename = typerolename
self.shapenames = shapenames
self.attrnames = attrnames
self.prefix = prefix
if strong:
self.namefmt = nodes.strong
else:
self.namefmt = addnodes.desc_name
class JoernTraversal(JoernObj):
doc_field_types = [
GroupedField('param',
label='Parameter',
names=('param', ),
can_collapse=False),
Field('in*', label='Ingoing nodes', names=('in*', ), has_arg=False),
NodeField('in', label='Ingoing nodes', names=('in', ), rolename='ref'),
Field('out*', label='Outgoing nodes', names=('out*', ), has_arg=False),
NodeField('out',
label='Outgoing nodes',
names=('out', ),
rolename='ref'),
]
desc_annotation = 'traversal'
def setup(app):
from sphinx.util.docfields import GroupedField
app.connect('autodocsumm-grouper', example_grouper)
app.add_object_type('confval',
'confval',
objname='configuration value',
indextemplate='pair: %s; configuration value')
fdesc = GroupedField('parameter',
label='Parameters',
names=['param'],
can_collapse=True)
app.add_object_type('event',
'event',
'pair: %s; event',
parse_event,
doc_field_types=[fdesc])
def setup(app):
from sphinx.ext.autodoc import cut_lines
from sphinx.util.docfields import GroupedField
app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
app.add_object_type('confval',
'confval',
objname='configuration value',
indextemplate='pair: %s; configuration value')
fdesc = GroupedField('parameter',
label='Parameters',
names=['param'],
can_collapse=True)
app.add_object_type('event',
'event',
'pair: %s; event',
parse_event,
doc_field_types=[fdesc])
def setup(app):
from sphinx.ext.autodoc import cut_lines
from sphinx.util.docfields import GroupedField
app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
app.add_object_type('confval', 'confval',
objname='configuration value',
indextemplate='pair: %s; configuration value')
fdesc = GroupedField('parameter', label='Parameters',
names=['param'], can_collapse=True)
app.add_object_type('event', 'event', 'pair: %s; event', parse_event,
doc_field_types=[fdesc])
# workaround for RTD
from sphinx.util import logging
logger = logging.getLogger(__name__)
app.info = lambda *args, **kwargs: logger.info(*args, **kwargs)
app.warn = lambda *args, **kwargs: logger.warning(*args, **kwargs)
app.debug = lambda *args, **kwargs: logger.debug(*args, **kwargs)
class DylanFunctionDesc(DylanBindingDesc):
"""A Dylan function, method, or generic function."""
doc_field_types = [
TypedField(
'parameters', label="Parameters", names=('param', 'parameter')),
GroupedField('values',
label="Values",
names=('value', 'val', 'retval', 'return')),
Field('signature',
label="Signature",
has_arg=False,
names=('sig', 'signature')),
Field('conditions',
label="Conditions",
has_arg=False,
names=('conditions', 'exceptions', 'signals', 'throws')),
] + DylanBindingDesc.doc_field_types
class JavaConstructor(JavaObject):
doc_field_types = [
TypedField('parameter',
label=_('Parameters'),
names=('param', 'parameter', 'arg', 'argument'),
typerolename='type',
typenames=('type', )),
GroupedField('throws', names=('throws', ), label=_('Throws'))
]
def handle_constructor_signature(self, sig, signode):
try:
member = javalang.parse.parse_constructor_signature(sig)
except javalang.parser.JavaSyntaxError:
raise self.error("syntax error in constructor signature")
if not isinstance(member, javalang.tree.ConstructorDeclaration):
raise self.error("expected constructor declaration")
mods = formatter.output_modifiers(member.modifiers).build()
signode += nodes.Text(mods + ' ', mods + ' ')
signode += addnodes.desc_name(member.name, member.name)
paramlist = addnodes.desc_parameterlist()
for parameter in member.parameters:
param = addnodes.desc_parameter('', '', noemph=True)
param += self._build_type_node(parameter.type)
if parameter.varargs:
param += nodes.Text('...', '')
param += nodes.emphasis(' ' + parameter.name, ' ' + parameter.name)
paramlist += param
signode += paramlist
param_reprs = [
formatter.output_type(param.type, with_generics=False).build()
for param in member.parameters
]
return '%s(%s)' % (member.name, ', '.join(param_reprs))
def get_index_text(self, package, type, name):
return _('%s (Java constructor)' % (name, ))
def get_doc_field_types(self):
return [
TypedField(self.field_name,
label=l_(self.field_label),
names=(self.field_name, ),
typerolename='msg',
typenames=('{0}-{1}'.format(self.field_name,
TYPE_SUFFIX), )),
TypedField(self.constant_name,
label=l_(self.constant_label),
names=(self.constant_name, ),
typerolename='msg',
typenames=('{0}-{1}'.format(self.constant_name,
TYPE_SUFFIX), )),
GroupedField('{0}-{1}'.format(self.constant_name, VALUE_SUFFIX),
label=l_('{0} (Value)'.format(self.constant_label)),
names=('{0}-{1}'.format(self.constant_name,
VALUE_SUFFIX), )),
]
class DmlProperty(DmlObject):
"""Description of a function."""
option_spec: OptionSpec = DmlObject.option_spec.copy()
option_spec.update({
'const': directives.flag,
'readonly': directives.flag,
'type': directives.unchanged,
})
doc_field_types = [
Field('default', label=_('Default'), names=('default')),
GroupedField('throws', label=_('Throws'), names=('throws', 'throw', 'error', 'err'), can_collapse=True)
]
def split_signature(self, sig: str) -> Tuple[str, str, List[str], List[str]]:
# return tuple:
# - type (class, property, event, function) -> str
# - name -> str
# - arglist -> List[str]
# - annotations -> List[str]
if not "type" in self.options:
raise Exception("DML property always needs type assigned")
typ = "property " + self.options["type"]
name = sig
arglist = None
annotations = []
if 'const' in self.options:
annotations.append("constant")
if 'readonly' in self.options:
annotations.append("readonly")
return (typ, name, arglist, annotations)
def get_index_text(self, name_cls: Tuple[str, str]) -> str:
# add index in own add_target_and_index() instead.
return "PropertyName " + name_cls[0]
class DylanClassDesc(DylanBindingDesc):
"""A Dylan class."""
display_name = "class"
annotations = [
'open', 'primary', 'free', 'abstract', 'concrete', 'instantiable',
'uninstantiable', 'sealed'
] + DylanBindingDesc.annotations
option_spec = dict(DylanBindingDesc.option_spec.items())
option_spec.update(
dict({
'open': DIRECTIVES.flag,
'primary': DIRECTIVES.flag,
'free': DIRECTIVES.flag,
'abstract': DIRECTIVES.flag,
'sealed': DIRECTIVES.flag,
'concrete': DIRECTIVES.flag,
'instantiable': DIRECTIVES.flag,
'uninstantiable': DIRECTIVES.flag,
}.items()))
doc_field_types = [
Field('superclasses',
label="Superclasses",
has_arg=False,
names=('supers', 'superclasses', 'super', 'superclass')),
TypedField('keyword',
label="Init-Keywords",
names=('keyword', 'init-keyword')),
GroupedField('slots', label="Slots", names=('slot', 'getter')),
Field('conditions',
label="Conditions",
has_arg=False,
names=('conditions', 'exceptions', 'condition', 'exception',
'signals', 'throws')),
Field('operations',
label="Operations",
has_arg=False,
names=('operations', 'methods', 'functions')),
] + DylanBindingDesc.doc_field_types
def setup(app):
from sphinx.ext.autodoc import cut_lines
from sphinx.util.docfields import GroupedField
app.connect("autodoc-process-docstring", cut_lines(4, what=["module"]))
app.add_object_type(
"confval",
"confval",
objname="configuration value",
indextemplate="pair: %s; configuration value",
)
fdesc = GroupedField("parameter",
label="Parameters",
names=["param"],
can_collapse=True)
app.add_object_type("event",
"event",
"pair: %s; event",
parse_event,
doc_field_types=[fdesc])
def setup(app):
app.add_description_unit('confval', 'confval',
'pair: %s; configuration value')
# original directives for index
from sphinx.util.docfields import GroupedField
fdesc = GroupedField('parameter', label='Parameters',
names=['param'], can_collapse=True)
app.add_object_type('blockdiag_diagram_attr',
'blockdiag_diagram_attr',
'pair: %s; diagram atttribute(blockdiag)',
parse_event, doc_field_types=[fdesc])
app.add_object_type('blockdiag_edge_attr',
'blockdiag_egde_attr',
'pair: %s; edge attribute(blockdiag)',
parse_event, doc_field_types=[fdesc])
app.add_object_type('blockdiag_node_attr',
'blockdiag_node_attr',
'pair: %s; node attribute(blockdiag)',
parse_event, doc_field_types=[fdesc])
class JSCallable(JSObject):
"""Description of a JavaScript function, method or constructor."""
has_arguments = True
doc_field_types = [
TypedField('arguments',
label=l_('Arguments'),
names=('argument', 'arg', 'parameter', 'param'),
typerolename='func',
typenames=('paramtype', 'type')),
GroupedField('errors',
label=l_('Throws'),
rolename='err',
names=('throws', ),
can_collapse=True),
Field('returnvalue',
label=l_('Returns'),
has_arg=False,
names=('returns', 'return')),
]
def setup(app):
from sphinx.util.docfields import GroupedField
app.add_object_type('confval',
'confval',
objname='configuration value',
indextemplate='pair: %s; configuration value')
fdesc = GroupedField('parameter',
label='Parameters',
names=['param'],
can_collapse=True)
app.add_object_type('event',
'event',
'pair: %s; event',
parse_event,
doc_field_types=[fdesc])
app.add_object_type('xpath-func', 'xpath', 'pair: %s; xpath-func',
parse_event)
app.connect('autodoc-skip-member', include_enum_values)
def setup(app: Sphinx) -> None:
"""
A `sphinx` ``setup()`` function setting up the :rst:dir:`event` directive
and :rst:role:`event` role.
"""
# this was taken from the sphinx conf.py file and creates the documenting
# directive `.. event::` and role `:event:` for documenting sphinx events
app.add_object_type(
directivename="event",
rolename="event",
indextemplate="pair: %s; event",
parse_node=parse_event,
doc_field_types=[
GroupedField(
"parameter",
label="Parameters",
names=("param", ),
can_collapse=True,
)
],
)
def setup(app):
from sphinx.ext.autodoc import cut_lines
from sphinx.util.docfields import GroupedField
app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
app.connect('source-read', linkify_issues_in_changelog)
app.add_object_type('confval',
'confval',
objname='configuration value',
indextemplate='pair: %s; configuration value')
app.add_object_type(
'setuptools-confval',
'setuptools-confval',
objname='setuptools configuration value',
indextemplate='pair: %s; setuptools configuration value')
fdesc = GroupedField('parameter',
label='Parameters',
names=['param'],
can_collapse=True)
app.add_object_type('event',
'event',
'pair: %s; event',
parse_event,
doc_field_types=[fdesc])
# Load jQuery and patches to make readthedocs-doc-embed.js available (refs: #10574)
app.add_js_file(
'https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js',
priority=100)
app.add_js_file(
'https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.13.1/underscore-min.js', # NoQA
priority=100)
app.add_js_file('_sphinx_javascript_frameworks_compat.js', priority=105)
# workaround for RTD
from sphinx.util import logging
logger = logging.getLogger(__name__)
app.info = lambda *args, **kwargs: logger.info(*args, **kwargs)
app.warn = lambda *args, **kwargs: logger.warning(*args, **kwargs)
app.debug = lambda *args, **kwargs: logger.debug(*args, **kwargs)
def setup(app):
from sphinx.util.docfields import GroupedField
app.srcdir = basedir
app.confdir = app.srcdir
app.add_object_type(
"confval",
"confval",
objname="configuration value",
indextemplate="pair: %s; configuration value",
)
fdesc = GroupedField(
"parameter", label="Parameters", names=["param"], can_collapse=True
)
# workaround for RTD
from sphinx.util import logging
logger = logging.getLogger(__name__)
app.info = lambda *args, **kwargs: logger.info(*args, **kwargs)
app.warn = lambda *args, **kwargs: logger.warning(*args, **kwargs)
app.debug = lambda *args, **kwargs: logger.debug(*args, **kwargs)
class Cmd(ObjectDescription):
doc_field_types = [
GroupedField('scope', label=('Scopes'), names=('scope',),
rolename='cmd'),
TypedField('parameter', label=('Parameters'),
names=('param', 'parameter', 'arg', 'argument'),
typerolename='type', typenames=('paramtype', 'type')),
]
def handle_signature(self, sig, signode):
sig = sig.split()
name = sig.pop(0)
cmd = [name]
while sig[0] != '|':
cmd.append(sig.pop(0))
cmd = ' '.join(cmd)
sig.pop(0)
signode += addnodes.desc_name(cmd, cmd)
signode += nodes.inline(' ', ' ')
signode += nodes.Text(' '.join(sig))
return cmd
def add_target_and_index(self, name, sig, signode):
target = 'lsctl.cmd.' + name
if target not in self.state.document.ids:
signode['names'].append(target)
signode['ids'].append(target)
signode['first'] = (not self.names)
self.state.document.note_explicit_target(signode)
cmds = self.env.domaindata['lsctl']['cmd']
cmds[name] = self.env.docname
index_name = '{} (LSCTL directive)'.format(name)
self.indexnode['entries'].append(('single', index_name, target, '', None))
class MatObject(ObjectDescription):
"""
Description of a general MATLAB object.
"""
option_spec = {
'noindex': directives.flag,
'module': directives.unchanged,
'annotation': 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 MATLAB signature into RST nodes.
Return (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
"""
m = mat_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('mat:module'))
if not self.env.config.matlab_keep_package_prefix:
modname = strip_package_prefix(modname)
name_prefix = strip_package_prefix(name_prefix)
name = strip_package_prefix(name)
classname = self.env.temp_data.get('mat: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('mat:module'))
if modname and modname != 'exceptions':
if not self.env.config.matlab_keep_package_prefix:
modname = strip_package_prefix(modname)
nodetext = modname + '.'
signode += addnodes.desc_addname(nodetext, nodetext)
anno = self.options.get('annotation')
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)
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return fullname, name_prefix
_pseudo_parse_arglist(signode, arglist)
if retann:
signode += addnodes.desc_returns(retann, retann)
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
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('mat:module'))
fullname = (modname and modname + '.' or '') + name_cls[0]
if not self.env.config.matlab_keep_package_prefix:
modname_out = strip_package_prefix(modname)
fullname_out = (modname_out and modname_out + '.'
or '') + name_cls[0]
else:
modname_out, fullname_out = modname, fullname
# note target
if fullname not in self.state.document.ids:
signode['names'].append(fullname_out)
signode['ids'].append(fullname)
signode['first'] = (not self.names)
self.state.document.note_explicit_target(signode)
objects = self.env.domaindata['mat']['objects']
if fullname in objects:
self.state_machine.reporter.warning(
'duplicate object description of %s, ' % fullname +
'other instance in ' +
self.env.doc2path(objects[fullname][0]) +
', use :noindex: for one of them',
line=self.lineno)
objects[fullname] = (self.env.docname, self.objtype)
indextext = self.get_index_text(modname_out, name_cls)
if indextext:
entry = ('single', indextext, fullname, '', None)
self.indexnode['entries'].append(entry)
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['mat:class'] = None
class ChapelObject(ObjectDescription):
"""Base class for Chapel directives. It has methods for parsing signatures of
any form, and generating target and index text.
"""
option_spec = {
'noindex': directives.flag,
'module': directives.unchanged,
'annotation': directives.unchanged,
}
doc_field_types = [
ChapelTypedField('parameter', label=_('Arguments'),
names=('param', 'parameter', 'arg', 'argument'),
typerolename='chplref',
typenames=('paramtype', 'type'),
can_collapse=True),
Field('returnvalue', label=_('Returns'), has_arg=False,
names=('returns', 'return')),
Field('yieldvalue', label=_('Yields'), has_arg=False,
names=('yields', 'yield')),
Field('returntype', label=_('Return type'), has_arg=False,
names=('rtype',)),
Field('yieldtype', label=_('Yield type'), has_arg=False,
names=('ytype',)),
GroupedField('errorhandling', label=_('Throws'),
names=('throw', 'throws'), can_collapse=True),
]
@staticmethod
def _pseudo_parse_arglist(signode, arglist):
"""Parse list of comma separated arguments.
Arguments can have optional types.
"""
paramlist = addnodes.desc_parameterlist()
stack = [paramlist]
try:
for argument in arglist.split(','):
argument = argument.strip()
ends_open = 0
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(']') and not 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)
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
def _get_attr_like_prefix(self, sig):
"""Return prefix text for attribute or data directive."""
sig_match = chpl_attr_sig_pattern.match(sig)
if sig_match is None:
return ChapelObject.get_signature_prefix(self, sig)
prefixes, _, _, _ = sig_match.groups()
if prefixes:
return prefixes.strip() + ' '
elif self.objtype == 'type':
return 'type' + ' '
else:
return ChapelObject.get_signature_prefix(self, sig)
def _get_proc_like_prefix(self, sig):
"""Return prefix text for function or method directive
(and similar).
"""
sig_match = chpl_sig_pattern.match(sig)
if sig_match is None:
return ChapelObject.get_signature_prefix(self, sig)
prefixes, _, _, _, _ = sig_match.groups()
if prefixes:
return prefixes.strip() + ' '
elif self.objtype.startswith('iter'):
return 'iter' + ' '
elif self.objtype in ('method', 'function'):
return 'proc' + ' '
else:
return ChapelObject.get_signature_prefix(self, sig)
def _is_attr_like(self):
"""Returns True when objtype is attribute or data."""
return self.objtype in ('attribute', 'data', 'type', 'enum')
def _is_proc_like(self):
"""Returns True when objtype is *function or *method."""
return (self.objtype in
('function', 'iterfunction', 'method', 'itermethod'))
def _get_sig_prefix(self, sig):
"""Return signature prefix text. For attribute, data, and proc/iter directives
this might be part of the signature. E.g. `type myNewType` will return
a prefix of 'type' and `inline proc foo()` will return 'inline proc'.
"""
if self._is_proc_like():
return self._get_proc_like_prefix(sig)
elif self._is_attr_like():
return self._get_attr_like_prefix(sig)
else:
return ChapelObject.get_signature_prefix(self, sig)
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):
"""Parse the signature *sig* into individual nodes and append them to the
*signode*. If ValueError is raises, parsing is aborted and the whole
*sig* string is put into a single desc_name node.
The return value is the value that identifies the object. IOW, it is
the identifier that will be used to reference this object, datum,
attribute, proc, etc. It is a tuple of "fullname" (including module and
class(es)) and the classes. See also :py:meth:`add_target_and_index`.
"""
if self._is_attr_like():
sig_match = chpl_attr_sig_pattern.match(sig)
if sig_match is None:
raise ValueError('Signature does not parse: {0}'.format(sig))
func_prefix, name_prefix, name, retann = sig_match.groups()
arglist = None
else:
sig_match = chpl_sig_pattern.match(sig)
if sig_match is None:
raise ValueError('Signature does not parse: {0}'.format(sig))
func_prefix, name_prefix, name, arglist, retann = \
sig_match.groups()
modname = self.options.get(
'module', self.env.temp_data.get('chpl:module'))
classname = self.env.temp_data.get('chpl:class')
if classname:
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:
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 func_prefix:
# signode += addnodes.desc_addname(func_prefix, func_prefix)
if name_prefix:
signode += addnodes.desc_addname(name_prefix, name_prefix)
anno = self.options.get('annotation')
signode += addnodes.desc_name(name, name)
if not arglist:
# If this needs an arglist, and parens were provided in the
# signature, add a parameterlist. Chapel supports paren-less
# functions and methods, which can act as computed properties. If
# arglist is the empty string, the signature included parens. If
# arglist is None, it did not include parens.
if self.needs_arglist() and arglist is not None:
# for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
if retann:
signode += addnodes.desc_type(retann, retann)
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return fullname, name_prefix
self._pseudo_parse_arglist(signode, arglist)
if retann:
signode += addnodes.desc_type(retann, retann)
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
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):
"""Add cross-reference IDs and entries to the index node, if
applicable. *name_cls* is the return value of
:py:meth:`handle_signature`.
"""
modname = self.options.get(
'module', self.env.temp_data.get('chpl: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['chpl']['objects']
if fullname in objects:
self.state_machine.reporter.warning(
'duplicate object description of %s, ' % fullname +
'other instance in ' +
self.env.doc2path(objects[fullname][0]) +
', use :noindex: for one of them',
line=self.lineno)
objects[fullname] = (self.env.docname, self.objtype)
indextext = self.get_index_text(modname, name_cls)
if indextext:
self.indexnode['entries'].append(('single', indextext,
fullname, '', None))
def before_content(self):
"""Called before parsing content. Set flag to help with class scoping.
"""
self.clsname_set = False
def after_content(self):
"""Called after parsing content. If any classes were added to the env
temp_data, make sure they are removed.
"""
if self.clsname_set:
self.env.temp_data.pop('chpl:class', None)
class CPPObject(ObjectDescription):
"""Description of a C++ language object."""
doc_field_types = [
GroupedField('parameter', label=l_('Parameters'),
names=('param', 'parameter', 'arg', 'argument'),
can_collapse=True),
GroupedField('exceptions', label=l_('Throws'), rolename='cpp:class',
names=('throws', 'throw', 'exception'),
can_collapse=True),
Field('returnvalue', label=l_('Returns'), has_arg=False,
names=('returns', 'return')),
]
def attach_name(self, node, name):
owner, name = name.split_owner()
varname = unicode(name)
if owner is not None:
owner = unicode(owner) + '::'
node += addnodes.desc_addname(owner, owner)
node += addnodes.desc_name(varname, varname)
def attach_type_suffixes(self, node, suffixes):
for suffix in suffixes:
node += nodes.Text(unicode(suffix))
def attach_type(self, node, type):
# XXX: link to c?
text = unicode(type)
pnode = addnodes.pending_xref(
'', refdomain='cpp', reftype='type',
reftarget=text, modname=None, classname=None)
pnode['cpp:parent'] = self.env.temp_data.get('cpp:parent')
pnode += nodes.Text(text)
node += pnode
def attach_modifiers(self, node, obj, visibility='public'):
if obj.visibility != visibility:
node += addnodes.desc_annotation(obj.visibility,
obj.visibility)
node += nodes.Text(' ')
if obj.static:
node += addnodes.desc_annotation('static', 'static')
node += nodes.Text(' ')
if getattr(obj, 'constexpr', False):
node += addnodes.desc_annotation('constexpr', 'constexpr')
node += nodes.Text(' ')
def add_target_and_index(self, sigobj, sig, signode):
theid = sigobj.get_id()
name = unicode(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['cpp']['objects'].setdefault(name,
(self.env.docname, self.objtype, theid))
indextext = self.get_index_text(name)
if indextext:
self.indexnode['entries'].append(('single', indextext, theid, ''))
def before_content(self):
lastname = self.names and self.names[-1]
if lastname and not self.env.temp_data.get('cpp:parent'):
assert isinstance(lastname, NamedDefExpr)
self.env.temp_data['cpp:parent'] = lastname.name
self.parentname_set = True
else:
self.parentname_set = False
def after_content(self):
if self.parentname_set:
self.env.temp_data['cpp: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, e:
self.state_machine.reporter.warning(e.description, line=self.lineno)
raise ValueError
self.describe_signature(signode, rv)
parent = self.env.temp_data.get('cpp:parent')
if parent is not None:
rv = rv.clone()
rv.name = rv.name.prefix(parent)
return rv
class PhpObject(ObjectDescription):
"""
Description of a general PHP object.
"""
option_spec = {
'noindex': directives.flag,
'module': directives.unchanged,
}
doc_field_types = [
TypedField('parameter', label=l_('Parameters'),
names=('param', 'parameter', 'arg', 'argument'),
typerolename='obj', typenames=('paramtype', 'type')),
TypedField('variable', label=l_('Variables'), rolename='obj',
names=('var', 'ivar', 'cvar'),
typerolename='obj', typenames=('vartype',)),
GroupedField('exceptions', label=l_('Throws'), rolename='exc',
names=('throws', 'throw', 'exception', 'except'),
can_collapse=True),
Field('returnvalue', label=l_('Returns'), has_arg=False,
names=('returns', 'return')),
Field('returntype', label=l_('Return type'), has_arg=False,
names=('rtype', 'returntype')),
]
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 PHP 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
"""
m = php_sig_re.match(sig)
if m is None:
raise ValueError
name_prefix, name, arglist, retann = m.groups()
if not name_prefix:
name_prefix = ""
# determine module and class name (if applicable), as well as full name
modname = self.options.get(
'namespace', self.env.temp_data.get('php:namespace'))
classname = self.env.temp_data.get('php:class')
separator = separators[self.objtype]
if self.objtype == 'global' or self.objtype == 'function':
add_module = False
modname = None
classname = None
fullname = name
else:
add_module = True
# name_prefix and a non-static method, means the classname was
# repeated. Trim off the <class>::
if name_prefix and self.objtype != 'staticmethod':
if name_prefix.startswith(classname):
name_prefix = name_prefix[len(classname):].rstrip('::')
classname = classname.rstrip('::')
fullname = name_prefix + classname + separator + name
elif name_prefix:
classname = classname.rstrip('::')
fullname = name_prefix + name
# Currently in a class, but not creating another class,
elif classname and not self.objtype in ['class', 'exception', 'interface', 'trait']:
if not self.env.temp_data['php:in_class']:
name_prefix = classname + separator
fullname = classname + separator + name
else:
classname = ''
fullname = name
signode['namespace'] = modname
signode['class'] = self.class_name = 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:
if modname and not self.env.temp_data['php:in_class']:
name_prefix = modname + NS + name_prefix
signode += addnodes.desc_addname(name_prefix, name_prefix)
elif add_module and self.env.config.add_module_names:
if self.objtype == 'global':
nodetext = ''
signode += addnodes.desc_addname(nodetext, nodetext)
else:
modname = self.options.get(
'namespace', self.env.temp_data.get('php:namespace'))
if modname and not self.env.temp_data.get('php:in_class', False):
nodetext = modname + NS
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
signode += addnodes.desc_parameterlist()
stack = [signode[-1]]
for token in php_paramlist_re.split(arglist):
if token == '[':
opt = addnodes.desc_optional()
stack[-1] += opt
stack.append(opt)
elif token == ']':
try:
stack.pop()
except IndexError:
raise ValueError
elif not token or token == ',' or token.isspace():
pass
else:
token = token.strip()
stack[-1] += addnodes.desc_parameter(token, token)
if len(stack) != 1:
raise ValueError
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 _is_class_member(self):
return self.objtype.startswith('method') or self.objtype.startswith('attr')
def add_target_and_index(self, name_cls, sig, signode):
if self.objtype == 'global':
modname = ''
else:
modname = self.options.get(
'namespace', self.env.temp_data.get('php:namespace'))
separator = separators[self.objtype]
if self._is_class_member():
if signode['class']:
prefix = modname and modname + NS or ''
else:
prefix = modname and modname + NS or ''
else:
prefix = modname and modname + NS or ''
fullname = prefix + 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['php']['objects']
if fullname in objects:
self.env.warn(
self.env.docname,
'duplicate object description of %s, ' % fullname +
'other instance in ' +
self.env.doc2path(objects[fullname][0]),
self.lineno)
objects[fullname] = (self.env.docname, self.objtype)
indextext = self.get_index_text(modname, name_cls)
if indextext:
self.indexnode['entries'].append(('single', indextext,
fullname, fullname))
class JavaType(JavaObject):
doc_field_types = [
GroupedField(
'parameter',
names=('param', ),
label=_('Parameters') # replaced the old "label=l_('Parameters')"
)
]
declaration_type = None
def handle_type_signature(self, sig, signode):
try:
member = javalang.parse.parse_type_signature(sig)
except javalang.parser.JavaSyntaxError:
raise self.error("syntax error in field signature")
if isinstance(member, javalang.tree.ClassDeclaration):
self.declaration_type = 'class'
elif isinstance(member, javalang.tree.InterfaceDeclaration):
self.declaration_type = 'interface'
elif isinstance(member, javalang.tree.EnumDeclaration):
self.declaration_type = 'enum'
elif isinstance(member, javalang.tree.AnnotationDeclaration):
self.declaration_type = 'annotation'
else:
raise self.error("expected type declaration")
mods = formatter.output_modifiers(member.modifiers).build()
signode += nodes.Text(mods + ' ', mods + ' ')
if self.declaration_type == 'class':
signode += nodes.Text('class ', 'class ')
elif self.declaration_type == 'interface':
signode += nodes.Text('interface ', 'interface ')
elif self.declaration_type == 'enum':
signode += nodes.Text('enum ', 'enum ')
elif self.declaration_type == 'annotation':
signode += nodes.Text('@interface ', '@interface ')
signode += addnodes.desc_name(member.name, member.name)
if self.declaration_type in ('class',
'interface') and member.type_parameters:
type_params = formatter.output_type_params(
member.type_parameters).build()
signode += nodes.Text(type_params, type_params)
if self.declaration_type == 'class':
if member.extends:
extends = ' extends '
signode += nodes.Text(extends, extends)
signode += self._build_type_node(member.extends)
if member.implements:
implements = ' implements '
signode += nodes.Text(implements, implements)
signode += self._build_type_node_list(member.implements)
elif self.declaration_type == 'interface':
if member.extends:
extends = ' extends '
signode += nodes.Text(extends, extends)
signode += self._build_type_node_list(member.extends)
elif self.declaration_type == 'enum':
if member.implements:
implements = ' implements '
signode += nodes.Text(implements, implements)
signode += self._build_type_node_list(member.implements)
return member.name
def get_index_text(self, package, type, name):
return _('%s (Java %s)' % (name, self.declaration_type))
class MongoDBObject(ObjectDescription):
"""
Description of a MongoDB object.
"""
#: If set to ``True`` this object is callable and a `desc_parameterlist` is
#: added
has_arguments = False
#: what is displayed right before the documentation entry
display_prefix = None
def handle_signature(self, sig, signode):
sig = sig.strip()
if '(' in sig and sig[-1:] == ')':
prefix, arglist = sig.split('(', 1)
prefix = prefix.strip()
arglist = arglist[:-1].strip()
else:
prefix = sig
arglist = None
if '.' in prefix:
nameprefix, name = prefix.rsplit('.', 1)
else:
nameprefix = None
name = prefix
objectname = self.env.temp_data.get('mongodb:object')
if nameprefix:
if objectname:
# someone documenting the method of an attribute of the current
# object? shouldn't happen but who knows...
nameprefix = objectname + '.' + nameprefix
fullname = nameprefix + '.' + name
elif objectname:
fullname = objectname + '.' + name
else:
# just a function or constructor
objectname = ''
fullname = name
signode['object'] = objectname
signode['fullname'] = fullname
if self.display_prefix:
signode += addnodes.desc_annotation(self.display_prefix,
self.display_prefix)
if nameprefix:
signode += addnodes.desc_addname(nameprefix + '.', nameprefix + '.')
signode += addnodes.desc_name(name, name)
if self.has_arguments:
if not arglist:
signode += addnodes.desc_parameterlist()
else:
_pseudo_parse_arglist(signode, arglist)
return fullname, nameprefix
def add_target_and_index(self, name_obj, sig, signode):
objectname = self.options.get(
'object', self.env.temp_data.get('mongodb:object'))
fullname = name_obj[0]
if fullname not in self.state.document.ids:
signode['names'].append(fullname)
signode['ids'].append(fullname.replace('$', '_S_'))
signode['first'] = not self.names
self.state.document.note_explicit_target(signode)
objects = self.env.domaindata['mongodb']['objects']
# if fullname in objects:
# self.state_machine.reporter.warning(
# 'duplicate object description of %s, ' % fullname +
# 'other instance in ' +
# self.env.doc2path(objects[fullname][0]),
# line=self.lineno)
objects[fullname] = self.env.docname, self.objtype
# elif self.objtype == "binary":
# signode['names'].append(fullname)
# signode['ids'].append(fullname.replace('$', '_S_'))
# signode['first'] = not self.names
# self.state.document.note_explicit_target(signode)
indextext = self.get_index_text(objectname, name_obj)
if indextext:
self.indexnode['entries'].append(('single', indextext,
fullname.replace('$', '_S_'),
''))
def get_index_text(self, objectname, name_obj):
name, obj = name_obj
if self.objtype == 'dbcommand':
return _('%s (database command)') % name
elif self.objtype == 'operator':
return _('%s (operator)') % name
elif self.objtype == 'projection':
return _('%s (projection operator)') % name
elif self.objtype == 'program':
return _('%s (program)') % name
elif self.objtype == 'setting':
return _('%s (setting)') % (name)
elif self.objtype == 'status':
return _('%s (status)') % (name)
elif self.objtype == 'stats':
return _('%s (statistic)') % (name)
elif self.objtype == 'data':
return _('%s (shell output)') % (name)
elif self.objtype == 'method':
return _('%s (shell method)') % (name)
elif self.objtype == 'collflag':
return _('%s (collection flag)') % (name)
elif self.objtype == 'readmode':
return _('%s (read preference mode)') % (name)
elif self.objtype == 'error':
return _('%s (error code)') % (name)
elif self.objtype == 'macro':
return _('%s (JavaScript shell macro)') % (name)
elif self.objtype == 'limit':
return _('%s (MongoDB system limit)') % (name)
return ''
def run(self):
return super(MongoDBObject, self).run()
doc_field_types = [
TypedField('arguments', label=l_('Arguments'),
names=('argument', 'arg', 'parameter', 'param'),
typerolename='method', typenames=('paramtype', 'type')),
TypedField('options', label=l_('Options'),
names=('options', 'opts', 'option', 'opt'),
typerolename=('dbcommand', 'setting', 'status', 'stats', 'aggregator'),
typenames=('optstype', 'type')),
TypedField('fields', label=l_('Fields'),
names=('fields', 'fields', 'field', 'field'),
typerolename=('dbcommand', 'setting', 'status', 'stats', 'aggregator'),
typenames=('fieldtype', 'type')),
TypedField('flags', label=l_('Flags'),
names=('flags', 'flags', 'flag', 'flag'),
typerolename=('dbcommand', 'setting', 'status', 'stats', 'aggregator'),
typenames=('flagtype', 'type')),
GroupedField('errors', label=l_('Throws'), rolename='err',
names=('throws', ),
can_collapse=True),
GroupedField('exception', label=l_('Exception'), rolename='err',
names=('exception', ),
can_collapse=True),
Field('returnvalue', label=l_('Returns'), has_arg=False,
names=('returns', 'return')),
Field('returntype', label=l_('Return type'), has_arg=False,
names=('rtype',)),
]
class JavaMethod(JavaObject):
doc_field_types = [
TypedField(
'parameter',
label=_('Parameters'), # replaced the old "label=l_('Parameters')"
names=('param', 'parameter', 'arg', 'argument'),
typerolename='type',
typenames=('type', )),
Field(
'returnvalue',
label=_('Returns'), # replaced the old "label=l_('Returns')"
has_arg=False,
names=('returns', 'return')),
GroupedField(
'throws',
names=('throws', ),
label=_('Throws'), # replaced the old "label=l_('Throws')"
rolename='type')
]
def handle_method_signature(self, sig, signode):
try:
member = javalang.parse.parse_member_signature(sig)
except javalang.parser.JavaSyntaxError:
raise self.error("syntax error in method signature")
if not isinstance(member, javalang.tree.MethodDeclaration):
raise self.error("expected method declaration")
mods = formatter.output_modifiers(member.modifiers).build()
signode += nodes.Text(mods + ' ', mods + ' ')
if member.type_parameters:
type_params = formatter.output_type_params(
member.type_parameters).build()
signode += nodes.Text(type_params, type_params)
signode += nodes.Text(' ', ' ')
rnode = addnodes.desc_type('', '')
rnode += self._build_type_node(member.return_type)
signode += rnode
signode += nodes.Text(' ', ' ')
signode += addnodes.desc_name(member.name, member.name)
paramlist = addnodes.desc_parameterlist()
for parameter in member.parameters:
param = addnodes.desc_parameter('', '', noemph=True)
param += self._build_type_node(parameter.type)
if parameter.varargs:
param += nodes.Text('...', '')
param += nodes.emphasis(' ' + parameter.name, ' ' + parameter.name)
paramlist += param
signode += paramlist
param_reprs = [
formatter.output_type(param.type, with_generics=False).build()
for param in member.parameters
]
return member.name + '(' + ', '.join(param_reprs) + ')'
def get_index_text(self, package, type, name):
return _('%s (Java method)' % (name, ))
class BsvObject(ObjectDescription):
"""
Description of a general Bsv object.
"""
option_spec = {
'noindex': directives.flag,
'package': directives.unchanged,
'annotation': directives.unchanged,
'parameter': directives.unchanged,
'returntype': directives.unchanged,
}
doc_field_types = [
TypedField('parameter',
label=l_('Parameters'),
names=('param', 'parameter', 'arg', 'argument', 'keyword',
'kwarg', 'kwparam'),
typerolename='obj',
typenames=('paramtype', 'type'),
can_collapse=True),
TypedField('variable',
label=l_('Variables'),
rolename='obj',
names=('var', 'ivar', 'cvar'),
typerolename='obj',
typenames=('vartype', ),
can_collapse=True),
GroupedField('exceptions',
label=l_('Raises'),
rolename='exc',
names=('raises', 'raise', 'exception', 'except'),
can_collapse=True),
Field('returnvalue',
label=l_('Returns'),
has_arg=False,
names=('returns', 'return')),
Field('returntype',
label=l_('Return type'),
has_arg=False,
names=('rtype', )),
]
def get_signatures(self):
siglines = ObjectDescription.get_signatures(self)
return siglines
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 Bsv signature into RST nodes.
Return (fully qualified name of the thing, interfacename if any).
If inside a interface, the current interface 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
"""
print('BsvObject.handle_signature', sig)
name_prefix = ''
name = sig
arglist = ''
retann = ''
if self.objtype in ['interface', 'instance', 'typeclass']:
split = sig.split('#', 1)
name = split[0]
if len(split) > 1:
arglist = split[1]
m = bsv_param_re.match(arglist)
if m: arglist = m.group(1)
elif self.objtype in ['subinterface', 'field']:
split = sig.rsplit(' ', 1)
print('rsplit', split)
name = split[-1]
if len(split) > 1:
retann = split[0]
elif self.objtype in ['method', 'function']:
split = sig.split(' ', 1)
retann = split[0]
nameparams = split[1]
split = nameparams.split('(', 1)
name = split[0]
if len(split) > 1:
arglist = split[1][0:-1]
elif self.objtype in ['module']:
split = sig.split('#', 1)
name = split[0]
if len(split) > 1:
depth = 0
paramreturn = split[1]
#print('module', paramreturn, len(paramreturn))
for i in range(0, len(paramreturn)):
c = paramreturn[i]
if c == '(': depth = depth + 1
elif c == ')': depth = depth - 1
#print(i, c, depth)
if depth == 0:
endofparam = i
break
arglist = paramreturn[1:endofparam]
retann = paramreturn[endofparam + 1:-1]
#print(arglist)
#print(endofparam, retann)
# determine package and interface name (if applicable), as well as full name
modname = self.options.get('package',
self.env.temp_data.get('bsv:package'))
interfacename = self.env.temp_data.get('bsv:interface')
if interfacename:
add_package = False
if name_prefix and name_prefix.startswith(interfacename):
fullname = name_prefix + name
# interface name is given again in the signature
name_prefix = name_prefix[len(interfacename):].lstrip('.')
elif name_prefix:
# interface name is given in the signature, but different
# (shouldn't happen)
fullname = interfacename + '.' + name_prefix + name
else:
# interface name is not given in the signature
fullname = interfacename + '.' + name
else:
add_package = True
if name_prefix:
interfacename = name_prefix.rstrip('.')
fullname = name_prefix + name
else:
interfacename = ''
fullname = name
signode['package'] = modname
signode['interface'] = interfacename
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' package.
elif add_package and self.env.config.add_package_names:
modname = self.options.get('package',
self.env.temp_data.get('bsv:package'))
if modname and modname != 'exceptions':
nodetext = modname + '::'
signode += addnodes.desc_addname(nodetext, nodetext)
anno = self.options.get('annotation')
signode += addnodes.desc_name(name, name)
#print('arglist', arglist)
if not arglist:
if self.needs_arglist():
# for callables, add an empty parameter list
if arglist:
signode += addnodes.desc_parameterlist(text=arglist)
elif self.options.get('parameter'):
signode += addnodes.desc_parameterlist(
text=self.options.get('parameter'))
if retann:
signode += addnodes.desc_returns(text=retann)
elif self.options.get('returntype'):
signode += addnodes.desc_returns(
text=self.options.get('returntype'))
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
#print('signode', signode)
return fullname, name_prefix
_pseudo_parse_arglist(signode, arglist)
if retann:
signode += addnodes.desc_returns(retann, retann)
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
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 subinterfacees')
def add_target_and_index(self, name_cls, sig, signode):
modname = self.options.get('package',
self.env.temp_data.get('bsv:package'))
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['bsv']['objects']
if fullname in objects:
self.state_machine.reporter.warning(
'duplicate object description of %s, ' % fullname +
'other instance in ' +
self.env.doc2path(objects[fullname][0]) +
', use :noindex: for one of them',
line=self.lineno)
objects[fullname] = (self.env.docname, self.objtype)
indextext = self.get_index_text(modname, name_cls)
if indextext:
self.indexnode['entries'].append(
('single', indextext, fullname, ''))
def before_content(self):
# needed for automatic qualification of members (reset in subinterfacees)
self.clsname_set = False
def after_content(self):
if self.clsname_set:
self.env.temp_data['bsv:interface'] = None
class HTTPResource(ObjectDescription):
doc_field_types = [
TypedField('parameter',
label='URL Parameters',
names=('param', 'parameter', 'arg', 'argument'),
can_collapse=False,
typerolename='obj',
typenames=('paramtype', 'type')),
GroupedField('queryparameter',
label='Query Parameters',
can_collapse=False,
names=('queryparameter', 'queryparam', 'qparam',
'query')),
GroupedField('formparameter',
label='Formdata Parameters',
names=('formparameter', 'formparam', 'fparam', 'form')),
GroupedField('statuscode',
label='Status Codes',
can_collapse=True,
rolename='statuscode',
names=('statuscode', 'status', 'code')),
Field('rawformdata',
label='Raw Data',
rolename='rawformdata',
has_arg=False,
names=('rawformdata', 'rfd', 'rawdata')),
Field('accesscontrol',
label='Accessible By',
rolename='accesscontrol',
has_arg=False,
names=('accesscontrol', )),
Field('shortname',
label='Short Name',
rolename='shortname',
has_arg=False,
names=('shortname', 'sn', 'view_func')),
Field('returns',
label='Returns',
rolename='returns',
has_arg=False,
names=('returns', 'ret', 'retval')),
]
method = NotImplemented
def handle_signature(self, sig, signode):
method = self.method.upper() + ' '
signode += addnodes.desc_name(method, method)
offset = 0
for match in http_sig_param_re.finditer(sig):
path = sig[offset:match.start()]
signode += addnodes.desc_name(path, path)
params = addnodes.desc_parameterlist()
typ = match.group('type')
if typ:
typ = typ + ': '
params += addnodes.desc_annotation(typ, typ)
name = match.group('name')
params += addnodes.desc_parameter(name, name)
signode += params
offset = match.end()
if offset < len(sig):
path = sig[offset:len(sig)]
signode += addnodes.desc_name(path, path)
fullname = self.method.upper() + ' ' + path
signode['method'] = self.method
signode['path'] = sig
signode['fullname'] = fullname
return (fullname, self.method, sig)
def needs_arglist(self):
return False
def add_target_and_index(self, name_cls, sig, signode):
sig = APIUtils.normalize_url(sig)
signode['ids'].append(http_resource_anchor(*name_cls[1:]))
self.env.domaindata['http'][self.method][sig] = (self.env.docname, '')
def get_index_text(self, modname, name):
return ''
class HTTPResource(ObjectDescription):
doc_field_types = [
TypedField('parameter',
label='Parameters',
names=('param', 'parameter', 'arg', 'argument'),
typerolename='obj',
typenames=('paramtype', 'type')),
TypedField('jsonparameter',
label='JSON Parameters',
names=('jsonparameter', 'jsonparam', 'json'),
typerolename='obj',
typenames=('jsonparamtype', 'jsontype')),
TypedField('requestjsonobject',
label='Request JSON Object',
names=('reqjsonobj', 'reqjson', '<jsonobj', '<json'),
typerolename='obj',
typenames=('reqjsonobj', '<jsonobj')),
TypedField('requestjsonarray',
label='Request JSON Array of Objects',
names=('reqjsonarr', '<jsonarr'),
typerolename='obj',
typenames=('reqjsonarrtype', '<jsonarrtype')),
TypedField('responsejsonobject',
label='Response JSON Object',
names=('resjsonobj', 'resjson', '>jsonobj', '>json'),
typerolename='obj',
typenames=('resjsonobj', '>jsonobj')),
TypedField('responsejsonarray',
label='Response JSON Array of Objects',
names=('resjsonarr', '>jsonarr'),
typerolename='obj',
typenames=('resjsonarrtype', '>jsonarrtype')),
TypedField('queryparameter',
label='Query Parameters',
names=('queryparameter', 'queryparam', 'qparam', 'query'),
typerolename='obj',
typenames=('queryparamtype', 'querytype', 'qtype')),
GroupedField('formparameter',
label='Form Parameters',
names=('formparameter', 'formparam', 'fparam', 'form')),
GroupedField('requestheader',
label='Request Headers',
rolename='header',
names=('<header', 'reqheader', 'requestheader')),
GroupedField('responseheader',
label='Response Headers',
rolename='header',
names=('>header', 'resheader', 'responseheader')),
GroupedField('statuscode',
label='Status Codes',
rolename='statuscode',
names=('statuscode', 'status', 'code'))
]
option_spec = {
'deprecated': directives.flag,
'noindex': directives.flag,
'synopsis': lambda x: x,
}
method = NotImplemented
def handle_signature(self, sig, signode):
method = self.method.upper() + ' '
signode += addnodes.desc_name(method, method)
offset = 0
path = None
for match in http_sig_param_re.finditer(sig):
path = sig[offset:match.start()]
signode += addnodes.desc_name(path, path)
params = addnodes.desc_parameterlist()
typ = match.group('type')
if typ:
typ += ': '
params += addnodes.desc_annotation(typ, typ)
name = match.group('name')
params += addnodes.desc_parameter(name, name)
signode += params
offset = match.end()
if offset < len(sig):
path = sig[offset:len(sig)]
signode += addnodes.desc_name(path, path)
assert path is not None, 'no matches for sig: %s' % sig
fullname = self.method.upper() + ' ' + path
signode['method'] = self.method
signode['path'] = sig
signode['fullname'] = fullname
return (fullname, self.method, sig)
def needs_arglist(self):
return False
def add_target_and_index(self, name_cls, sig, signode):
signode['ids'].append(http_resource_anchor(*name_cls[1:]))
if 'noindex' not in self.options:
self.env.domaindata['http'][self.method][sig] = (self.env.docname,
self.options.get(
'synopsis',
''),
'deprecated'
in self.options)
def get_index_text(self, modname, name):
return ''
class MongoDBObject(ObjectDescription):
"""
Description of a MongoDB object.
"""
#: If set to ``True`` this object is callable and a `desc_parameterlist` is
#: added
has_arguments = False
#: what is displayed right before the documentation entry
display_prefix = None
def handle_signature(self, sig, signode):
sig = sig.strip()
if '(' in sig and sig[-1:] == ')':
prefix, arglist = sig.split('(', 1)
prefix = prefix.strip()
arglist = arglist[:-1].strip()
else:
prefix = sig
arglist = None
if '.' in prefix:
nameprefix, name = prefix.rsplit('.', 1)
else:
nameprefix = None
name = prefix
objectname = self.env.temp_data.get('mongodb:object')
if nameprefix:
if objectname:
# someone documenting the method of an attribute of the current
# object? shouldn't happen but who knows...
nameprefix = objectname + '.' + nameprefix
fullname = nameprefix + '.' + name
elif objectname:
fullname = objectname + '.' + name
else:
# just a function or constructor
objectname = ''
fullname = name
signode['object'] = objectname
signode['fullname'] = fullname
if self.display_prefix:
signode += addnodes.desc_annotation(self.display_prefix,
self.display_prefix)
if nameprefix:
if nameprefix in conf['suppress-prefix']:
pass
else:
nameprefix += '.'
for prefix in conf['suppress-prefix']:
if nameprefix.startswith(prefix):
nameprefix = nameprefix[len(prefix)+1:]
break
signode += addnodes.desc_addname(nameprefix, nameprefix)
nameprefix[:-1]
signode += addnodes.desc_name(name, name)
if self.has_arguments:
if not arglist:
signode += addnodes.desc_parameterlist()
else:
_pseudo_parse_arglist(signode, arglist)
return fullname, nameprefix
def add_target_and_index(self, name_obj, sig, signode):
objectname = self.options.get(
'object', self.env.temp_data.get('mongodb:object'))
if self.objtype != 'program' and self.objtype in conf['prepend'].keys():
fullname = '.'.join([conf['prepend'][self.objtype], name_obj[0]])
elif name_obj[0] in self.state.document.ids:
fullname = 'iddup.' + name_obj[0]
else:
fullname = name_obj[0]
signode['names'].append(fullname)
signode['ids'].append(fullname.replace('$', '_S_').replace(' ', '-'))
signode['first'] = not self.names
self.state.document.note_explicit_target(signode)
objects = self.env.domaindata['mongodb']['objects']
if fullname in objects:
path = self.env.doc2path(self.env.domaindata['mongodb']['objects'][fullname][0])
spath = basename(path)
sspath = basename(self.state_machine.reporter.source)
if spath in conf['composites']:
pass
elif sspath in conf['composites']:
pass
elif spath == fullname:
pass
elif spath == fullname.lstrip('$'):
pass
elif spath == fullname.lstrip('_'):
pass
elif path == self.state_machine.reporter.source:
pass
elif fullname.startswith(spath):
pass
elif fullname == '$':
pass
# temporary: silencing the positional operator
# warning, this is the namespace clash for
# projection and query/update operators.
else:
self.state_machine.reporter.warning(
'duplicate object description of "%s", ' % fullname +
'other instance in ' + path,
line=self.lineno)
if os.path.basename(self.env.docname) in conf['composites']:
pass
else:
objects[fullname] = self.env.docname, self.objtype
indextext = self.get_index_text(objectname, name_obj)
if indextext:
self.indexnode['entries'].append(('single', indextext,
fullname.replace('$', '_S_'),
''))
def get_index_text(self, objectname, name_obj):
name, obj = name_obj
for directive in conf['directives']:
if self.objtype == directive['name']:
return _('%s (' + directive['description'] + ')') % name
return ''
def run(self):
return super(MongoDBObject, self).run()
doc_field_types = [
TypedField('arguments', label=l_('Arguments'),
names=('argument', 'arg'),
typerolename='method', typenames=('paramtype', 'type')),
TypedField('options', label=l_('Options'),
names=('options', 'opts', 'option', 'opt'),
typerolename=('dbcommand', 'setting', 'status', 'stats', 'aggregator', 'data'),
typenames=('optstype', 'type')),
TypedField('parameters', label=l_('Parameters'),
names=('param', 'paramter', 'parameters'),
typerolename=('dbcommand', 'setting', 'status', 'stats', 'aggregator', 'data'),
typenames=('paramtype', 'type')),
TypedField('fields', label=l_('Fields'),
names=('fields', 'fields', 'field', 'field'),
typerolename=('dbcommand', 'setting', 'status', 'stats', 'aggregator', 'data'),
typenames=('fieldtype', 'type')),
TypedField('flags', label=l_('Flags'),
names=('flags', 'flags', 'flag', 'flag'),
typerolename=('dbcommand', 'setting', 'status', 'stats', 'aggregator', 'data'),
typenames=('flagtype', 'type')),
GroupedField('errors', label=l_('Throws'), rolename='err',
names=('throws', ),
can_collapse=True),
GroupedField('exception', label=l_('Exception'), rolename='err',
names=('exception', ),
can_collapse=True),
Field('returnvalue', label=l_('Returns'), has_arg=False,
names=('returns', 'return')),
Field('returntype', label=l_('Return type'), has_arg=False,
names=('rtype',)),
]
class HTTPResource(ObjectDescription):
doc_field_types = [
TypedField(
"parameter",
label="Parameters",
names=("param", "parameter", "arg", "argument"),
typerolename="obj",
typenames=("paramtype", "type"),
),
TypedField(
"jsonparameter",
label="JSON Parameters",
names=("jsonparameter", "jsonparam", "json"),
typerolename="obj",
typenames=("jsonparamtype", "jsontype"),
),
TypedField(
"queryparameter",
label="Query Parameters",
names=("queryparameter", "queryparam", "qparam", "query"),
typerolename="obj",
typenames=("queryparamtype", "querytype", "qtype"),
),
GroupedField(
"formparameter",
label="Form Parameters",
names=("formparameter", "formparam", "fparam", "form"),
),
GroupedField(
"requestheader",
label="Request Headers",
rolename="mailheader",
names=("reqheader", "requestheader"),
),
GroupedField(
"responseheader",
label="Response Headers",
rolename="mailheader",
names=("resheader", "responseheader"),
),
GroupedField(
"statuscode",
label="Status Codes",
rolename="statuscode",
names=("statuscode", "status", "code"),
),
]
method = NotImplemented
def handle_signature(self, sig, signode):
method = self.method.upper() + " "
signode += addnodes.desc_name(method, method)
offset = 0
for match in http_sig_param_re.finditer(sig):
path = sig[offset:match.start()]
signode += addnodes.desc_name(path, path)
params = addnodes.desc_parameterlist()
typ = match.group("type")
if typ:
typ = typ + ": "
params += addnodes.desc_annotation(typ, typ)
name = match.group("name")
params += addnodes.desc_parameter(name, name)
signode += params
offset = match.end()
if offset < len(sig):
path = sig[offset:len(sig)]
signode += addnodes.desc_name(path, path)
fullname = self.method.upper() + " " + path
signode["method"] = self.method
signode["path"] = sig
signode["fullname"] = fullname
return (fullname, self.method, sig)
def needs_arglist(self):
return False
def add_target_and_index(self, name_cls, sig, signode):
signode["ids"].append(http_resource_anchor(*name_cls[1:]))
self.env.domaindata["http"][self.method][sig] = (self.env.docname, "")
def get_index_text(self, modname, name):
return ""
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# Monkey patch in a field type for columns.
# try:
from sphinx.util.docfields import Field, GroupedField, TypedField
from sphinx.domains.python import PythonDomain, PyObject, l_, PyField, PyTypedField
PyObject.doc_field_types += [
GroupedField('modelparam', label='Model Parameters', names=('modelparam', ), can_collapse=True,
rolename='math'
),
PyTypedField('expparam',
label=l_('Experiment Parameters'), names=('expparam', ), can_collapse=False,
rolename='obj'
),
PyField('scalar-expparam',
label=l_('Experiment Parameter'), names=('scalar-expparam', ),
has_arg=True, rolename='obj'
),
GroupedField('columns', label=l_('Columns'), names=('column', ), can_collapse=True),
]
# except:
# pass
###############################################################################
