def declaration_to_content(obj: summary.DeclarationSummary):
if obj.value:
default = nodes.paragraph(text="Default: ")
default += addnodes.literal_strong(text=str(obj.value))
yield default
if obj.location:
location = nodes.paragraph(text=f"Linkable {obj.location_type}: ")
location += addnodes.literal_strong(text=str(obj.location))
yield location
for comment in obj.comments:
yield nodes.paragraph(comment,
text=util.remove_comment_characters(comment))
def handle_item(fieldarg, content):
# type: (unicode, unicode) -> nodes.paragraph
par = nodes.paragraph()
# Adding the next line, and taking out the one after should prevent
# ivars from getting incorrect cross-references.
par += addnodes.literal_strong('', fieldarg)
#par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
# addnodes.literal_strong, env=env))
if fieldarg in types:
par += nodes.Text(' (')
# NOTE: using .pop() here to prevent a single type node to be
# inserted twice into the doctree, which leads to
# inconsistencies later when references are resolved
fieldtype = types.pop(fieldarg)
if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
typename = u''.join(n.astext() for n in fieldtype)
par.extend(
self.make_xrefs(self.typerolename,
domain,
typename,
addnodes.literal_emphasis,
env=env))
else:
par += fieldtype
par += nodes.Text(')')
par += nodes.Text(' -- ')
par += content
return par
def handle_item(fieldarg, content):
par = nodes.paragraph()
par += addnodes.literal_strong('', fieldarg) # Patch: this line added
# par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
# addnodes.literal_strong))
if fieldarg in types:
par += nodes.Text(' (')
# NOTE: using .pop() here to prevent a single type node to be
# inserted twice into the doctree, which leads to
# inconsistencies later when references are resolved
fieldtype = types.pop(fieldarg)
if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
typename = u''.join(n.astext() for n in fieldtype)
typename = typename.replace('int', 'python:int')
typename = typename.replace('long', 'python:long')
typename = typename.replace('float', 'python:float')
typename = typename.replace('type', 'python:type')
par.extend(
self.make_xrefs(self.typerolename, domain, typename,
addnodes.literal_emphasis, **kw))
else:
par += fieldtype
par += nodes.Text(')')
par += nodes.Text(' -- ')
par += content
return par
def build_portnamespace_doctree(self, portnamespace):
"""
Builds the doctree for a port namespace.
"""
from aiida.work.process import PortNamespace
result = nodes.bullet_list(bullet='*')
for name, port in sorted(portnamespace.items()):
if name.startswith(
'_'
) and self.HIDDEN_PORTS_FLAG not in self.options:
continue
if name == 'dynamic':
continue
item = nodes.list_item()
if isinstance(port, (InputPort, OutputPort)):
item += self.build_port_paragraph(name, port)
elif isinstance(port, PortNamespace):
# item += addnodes.literal_strong(
# text='Namespace {}'.format(name)
# )
item += addnodes.literal_strong(text=name)
item += nodes.Text(', ')
item += nodes.emphasis(text='Namespace')
item += self.build_portnamespace_doctree(port)
else:
raise NotImplementedError
result += item
return result
def missing_reference_handler(app, env, pendingXRefNode, contnode):
"""
Collect missing xref and return a node with "undefined" class that can
be used for styling.
Xrefs are collected in env.sphinxxrefs_unknowns list with a record
'refdoc','refdomain','reftype', 'reftarget', 'refexplicit', 'refwarn'.
"""
#--------------------- add entry to sphinxxrefs_unknowns list
if not hasattr(env, 'sphinxxrefs_unknowns'):
env.sphinxxrefs_unknowns = []
attributes = ('refdoc','refdomain','reftype', 'reftarget', 'refexplicit', 'refwarn')
unknown_entry = { k : pendingXRefNode[k] for k in attributes }
env.sphinxxrefs_unknowns.append(unknown_entry)
env.warn(
pendingXRefNode['refdoc'],
'reference not found: %s' % pendingXRefNode['reftarget'],
lineno=None)
if debug:
print 'missing entry',unknown_entry
#--------------------- change the node with a node with "undefined" calss
newnode = addnodes.literal_strong()
newnode['classes'] = contnode['classes']+['undefined']
content=contnode.children[0]
newnode.append(content)
return newnode
def build_portnamespace_doctree(self, port_namespace):
"""
Builds the doctree for a port namespace.
"""
from aiida.engine.processes.ports import InputPort, PortNamespace
if not port_namespace:
return None
result = nodes.bullet_list(bullet='*')
for name, port in sorted(port_namespace.items()):
item = nodes.list_item()
if _is_non_db(
port) and self.HIDE_UNSTORED_INPUTS_FLAG in self.options:
continue
if isinstance(port, (InputPort, OutputPort)):
item.extend(self.build_port_content(name, port))
elif isinstance(port, PortNamespace):
item += addnodes.literal_strong(text=name)
item += nodes.Text(', ')
item += nodes.emphasis(text='Namespace')
if port.help is not None:
item += nodes.Text(' -- ')
item.extend(publish_doctree(port.help)[0].children)
sub_doctree = self.build_portnamespace_doctree(port)
if sub_doctree:
from sphinxcontrib.details.directive import details, summary
sub_item = details(
opened=self.EXPAND_NAMESPACES_FLAG in self.options)
sub_item += summary(text='Namespace Ports')
sub_item += sub_doctree
item += sub_item
else:
raise NotImplementedError
result += item
return result
def resolve_required_by_xrefs(app, env, node, contnode):
"""Now that all recipes and packages have been parsed, we are called here
for each ``pending_xref`` node that sphinx has not been able to resolve.
We handle specifically the ``requiredby`` reftype created by the
`RequiredByField` fieldtype allowed in ``conda:package::``
directives, where we replace the ``pending_ref`` node with a bullet
list of reference nodes pointing to the package pages that
"depended" on the package.
"""
if node['reftype'] == 'requiredby' and node['refdomain'] == 'conda':
target = node['reftarget']
docname = node['refdoc']
backrefs = env.domains['conda'].data['backrefs'].get(target, set())
listnode = nodes.bullet_list()
for back_docname, back_target in backrefs:
par = nodes.paragraph()
name_node = addnodes.literal_strong(back_target,
back_target,
classes=['xref', 'backref'])
refnode = make_refnode(app.builder, docname, back_docname,
back_target, name_node)
refnode.set_class('conda-package')
par += refnode
listnode += nodes.list_item('', par)
return listnode
def handle_item(fieldarg, content):
par = nodes.paragraph()
par += addnodes.literal_strong('', fieldarg) # Patch: this line added
# par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
# addnodes.literal_strong))
if fieldarg in types:
par += nodes.Text(' (')
# NOTE: using .pop() here to prevent a single type node to be
# inserted twice into the doctree, which leads to
# inconsistencies later when references are resolved
fieldtype = types.pop(fieldarg)
if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
typename = fieldtype[0].astext()
builtin_types = ['int', 'long', 'float', 'bool', 'type']
for builtin_type in builtin_types:
pattern = fr'(?<![\w.]){builtin_type}(?![\w.])'
repl = f'python:{builtin_type}'
typename = re.sub(pattern, repl, typename)
par.extend(
self.make_xrefs(self.typerolename, domain, typename,
addnodes.literal_emphasis, **kw))
else:
par += fieldtype
par += nodes.Text(')')
par += nodes.Text(' -- ')
par += content
return par
def command_parse(env, sig, signode):
# x, y = sig.split()
signode += addnodes.literal_strong(sig, sig)
# signode += addnodes.desc_name(x, x)
# signode += addnodes.desc_parameterlist()
# signode[-1] += addnodes.desc_parameter(y, y)
return sig
def resolve_required_by_xrefs(app, env, node, contnode):
"""Now that all recipes and packages have been parsed, we are called here
for each ``pending_xref`` node that sphinx has not been able to resolve.
We handle specifically the ``requiredby`` reftype created by the
`RequiredByField` fieldtype allowed in ``conda:package::``
directives, where we replace the ``pending_ref`` node with a bullet
list of reference nodes pointing to the package pages that
"depended" on the package.
"""
if node['reftype'] == 'requiredby' and node['refdomain'] == 'conda':
target = node['reftarget']
docname = node['refdoc']
backrefs = env.domains['conda'].data['backrefs'].get(target, set())
listnode = nodes.bullet_list()
for back_docname, back_target in backrefs:
par = nodes.paragraph()
name_node = addnodes.literal_strong(back_target, back_target,
classes=['xref', 'backref'])
refnode = make_refnode(app.builder, docname,
back_docname, back_target, name_node)
refnode.set_class('conda-package')
par += refnode
listnode += nodes.list_item('', par)
return listnode
def handle_item(fieldarg, content):
par = nodes.paragraph()
par += addnodes.literal_strong('', fieldarg) # Patch: this line added
# par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
# addnodes.literal_strong))
if fieldarg in types:
par += nodes.Text(' (')
# NOTE: using .pop() here to prevent a single type node to be
# inserted twice into the doctree, which leads to
# inconsistencies later when references are resolved
fieldtype = types.pop(fieldarg)
if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
typename = u''.join(n.astext() for n in fieldtype)
typename = typename.replace('int', 'python:int')
typename = typename.replace('long', 'python:long')
typename = typename.replace('float', 'python:float')
typename = typename.replace('type', 'python:type')
par.extend(self.make_xrefs(self.typerolename, domain, typename,
addnodes.literal_emphasis, **kw))
else:
par += fieldtype
par += nodes.Text(')')
par += nodes.Text(' -- ')
par += content
return par
def handle_item(fieldarg, content):
# type: (str, str) -> nodes.paragraph
par = nodes.paragraph()
par += addnodes.literal_strong("", fieldarg) # Patch: this line added
# par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
# addnodes.literal_strong, env=env))
if fieldarg in types:
par += nodes.Text(" (")
# NOTE: using .pop() here to prevent a single type node to be
# inserted twice into the doctree, which leads to
# inconsistencies later when references are resolved
fieldtype = types.pop(fieldarg)
if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
typename = u"".join(n.astext() for n in fieldtype)
par.extend(
self.make_xrefs(
self.typerolename,
domain,
typename,
addnodes.literal_emphasis,
env=env,
))
else:
par += fieldtype
par += nodes.Text(")")
par += nodes.Text(" -- ")
par += content
return par
def handle_item(fieldarg, content):
"""description"""
par = nodes.paragraph()
par += addnodes.literal_strong("", fieldarg) # Patch: this line added
# par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
# addnodes.literal_strong))
if fieldarg in types:
par += nodes.Text(" (")
# NOTE: using .pop() here to prevent a single type node to be
# inserted twice into the doctree, which leads to
# inconsistencies later when references are resolved
fieldtype = types.pop(fieldarg)
if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
typename = "".join(n.astext() for n in fieldtype)
typename = typename.replace("int", "python:int")
typename = typename.replace("long", "python:long")
typename = typename.replace("float", "python:float")
typename = typename.replace("type", "python:type")
par.extend(
self.make_xrefs(
self.typerolename,
domain,
typename,
addnodes.literal_emphasis,
**kw,
))
else:
par += fieldtype
par += nodes.Text(")")
par += nodes.Text(" -- ")
par += content
return par
def build_portnamespace_doctree(self, port_namespace):
"""
Builds the doctree for a port namespace.
"""
from aiida.work.ports import InputPort, PortNamespace
result = nodes.bullet_list(bullet='*')
for name, port in sorted(port_namespace.items()):
item = nodes.list_item()
if _is_non_db(
port) and self.HIDE_UNSTORED_INPUTS_FLAG in self.options:
continue
if isinstance(port, (InputPort, OutputPort)):
item += self.build_port_paragraph(name, port)
elif isinstance(port, PortNamespace):
item += addnodes.literal_strong(text=name)
item += nodes.Text(', ')
item += nodes.emphasis(text='Namespace')
if port.help is not None:
item += nodes.Text(' -- ')
item.extend(publish_doctree(port.help)[0].children)
item += self.build_portnamespace_doctree(port)
else:
raise NotImplementedError
result += item
return result
def missing_reference_handler(app, env, pendingXRefNode, contnode):
"""
Collect missing xref and return a node with "undefined" class that can
be used for styling.
Xrefs are collected in env.sphinxxrefs_unknowns list with a record
'refdoc','refdomain','reftype', 'reftarget', 'refexplicit', 'refwarn'.
"""
# --------------------- add entry to sphinxxrefs_unknowns list
if not hasattr(env, "sphinxxrefs_unknowns"):
env.sphinxxrefs_unknowns = []
attributes = ("refdoc", "refdomain", "reftype", "reftarget", "refexplicit", "refwarn")
unknown_entry = {k: pendingXRefNode[k] for k in attributes}
env.sphinxxrefs_unknowns.append(unknown_entry)
env.warn(pendingXRefNode["refdoc"], "reference not found: %s" % pendingXRefNode["reftarget"], lineno=None)
if debug:
print "missing entry", unknown_entry
# --------------------- change the node with a node with "undefined" calss
newnode = addnodes.literal_strong()
newnode["classes"] = contnode["classes"] + ["undefined"]
content = contnode.children[0]
newnode.append(content)
return newnode
def parse_node(env, text, node):
args = text.split("^")
name = args[0].strip()
node += addnodes.literal_strong(name, name)
if len(args) > 2:
default = f"={args[2].strip()}"
node += nodes.literal(text=default)
if len(args) > 1:
content = f"({args[1].strip()})"
node += addnodes.compact_paragraph(text=content)
return name # this will be the link
def build_port_paragraph(self, name, port):
"""
Build the paragraph that describes a single port.
"""
paragraph = nodes.paragraph()
paragraph += addnodes.literal_strong(text=name)
paragraph += nodes.Text(', ')
paragraph += nodes.emphasis(
text=self.format_valid_types(port.valid_type)
)
paragraph += nodes.Text(', ')
paragraph += nodes.Text('required' if port.required else 'optional')
if port.help:
paragraph += nodes.Text(' -- ')
paragraph += nodes.Text(port.help)
return paragraph
def _doxylink_handler(name, rawtext, text, lineno, inliner, options={}, content=[]):
m = re.match(r'^(.+?)(?:<(.+?)>)?$', text)
title, name = m.groups()
name = name or title
url = get_url(name)
if not url:
print("ERROR: Could not find", name)
exit(1)
node = addnodes.literal_strong(title, title)
if url:
url = url_base + url
node = nodes.reference(
'', '', node, refuri=url
)
return [node], []
def build_port_content(self, name, port):
"""
Build the content that describes a single port.
"""
res = []
res.append(addnodes.literal_strong(text=name))
res.append(nodes.Text(', '))
res.append(
nodes.emphasis(text=self.format_valid_types(port.valid_type)))
res.append(nodes.Text(', '))
res.append(nodes.Text('required' if port.required else 'optional'))
if _is_non_db(port):
res.append(nodes.Text(', '))
res.append(nodes.emphasis(text='non_db'))
if port.help:
res.append(nodes.Text(' -- '))
# publish_doctree returns <document: <paragraph...>>.
# Here we only want the content (children) of the paragraph.
res.extend(publish_doctree(port.help)[0].children)
return res
def build_portnamespace_doctree(self, port_namespace):
"""Build the doctree for a port namespace."""
if not port_namespace:
return None
result = nodes.bullet_list(bullet='*')
for name, port in sorted(port_namespace.items(),
key=lambda item:
(item[1].required, not item[1].name),
reverse=True):
item = nodes.list_item()
if isinstance(port, InputGeneratorPort):
item.extend(self.build_port_content(name, port))
elif isinstance(port, PortNamespace):
if port.required:
item += addnodes.literal_strong(text=name)
else:
item.append(nodes.Text(name))
if port.help:
item += nodes.Text(f': {port.help}')
item += self.build_portnamespace_doctree(port)
else:
raise NotImplementedError
result += item
return result
def handle_item(fieldarg, content):
# type: (unicode, unicode) -> nodes.paragraph
par = nodes.paragraph()
# Adding the next line, and taking out the one after should prevent
# ivars from getting incorrect cross-references.
par += addnodes.literal_strong('', fieldarg)
#par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
# addnodes.literal_strong, env=env))
if fieldarg in types:
par += nodes.Text(' (')
# NOTE: using .pop() here to prevent a single type node to be
# inserted twice into the doctree, which leads to
# inconsistencies later when references are resolved
fieldtype = types.pop(fieldarg)
if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
typename = u''.join(n.astext() for n in fieldtype)
par.extend(self.make_xrefs(self.typerolename, domain, typename,
addnodes.literal_emphasis, env=env))
else:
par += fieldtype
par += nodes.Text(')')
par += nodes.Text(' -- ')
par += content
return par
