def model_section(species, model):
section = nodes.section(
ids=[f"sec_catalog_{species.id}_models_{model.id}"])
section += nodes.title(text=model.name)
section += nodes.paragraph(text=model.description)
section += nodes.rubric(text="Details")
section += model_table(model)
section += nodes.rubric(text="Populations")
section += population_list(model)
section += nodes.rubric(text="Citations")
section += citation_list(model)
section += nodes.rubric(text="Model parameters")
section += model_parameter_table(model)
return section
def model_section(self, species, model):
mid = self.get_demographic_model_id(species, model)
target = self.get_target(mid)
section = nodes.section(ids=[mid])
section += nodes.title(text=model.description)
section += nodes.paragraph(text=model.long_description)
section += nodes.rubric(text="Details")
section += self.model_summary(model)
section += nodes.rubric(text="Populations")
section += self.population_table(model)
section += nodes.rubric(text="Citations")
section += self.citation_list(model)
section += nodes.rubric(text="Demographic Model parameters")
section += self.model_parameter_table(species, model)
return [target, section]
def get_solution_elements(self, sol):
ex = self.get_exercise_node(sol)
try:
refuri = self.app.builder.get_relative_uri(
self.env.docname, ex.source) + '#' + ex['ids'][0]
except NoUri:
refuri = ''
title_text = get_exercise_title(self.env, ex)
return nodes.section(
'',
nodes.rubric(
'',
'',
nodes.reference(title_text,
title_text,
refuri=refuri,
refdocname=ex.source),
*[nodes.Text(' - ' + ex['title'])] if ex['title'] else [],
),
*sol.children,
ids=[
'solution-' +
('.'.join(map(str, get_exercise_number(self.env, ex))))
])
def run(self):
self.assert_has_content()
# Unique exercise identifier (each document)
serial_no = self.env.new_serialno('sphinx.ext.exercises')
target = nodes.target('', '', ids=[f'{self.name}-{serial_no}'])
# Build new exercise
exercise_node = exercise(self.content,
*[nodes.rubric(_('Exercise'), _('Exercise'))],
ids=[f'{self.name}-{serial_no}'],
**self.options)
# Recursively parse the exercise's content
self.state.nested_parse(self.content, self.content_offset,
exercise_node)
# Save metadata
exercise_node.update_all_atts(
{'title': self.arguments[0] if self.arguments else ''},
and_source=True)
# Get source line/code for later
exercise_node.source = self.env.docname
exercise_node.line = self.lineno
return [target, exercise_node]
def process_gallery_overview(app, doctree, fromdocname):
env = app.builder.env
if not hasattr(env, 'all_gallery_overview'):
env.all_gallery_overview = []
for node in doctree.traverse(gallery_xrefs):
ref_dict = {}
for s in env.all_gallery_overview:
sp = s['docname'].split('/')
if node.subfolder == 'all' or sp[-2] == node.subfolder:
letter = sp[-1][0].upper()
if letter in ref_dict and not s in ref_dict[letter]:
ref_dict[letter].append(s)
else:
ref_dict[letter] = [s]
content = []
for letter, refs in sorted(ref_dict.items()):
para = nodes.paragraph()
para += nodes.rubric((_(letter)), (_(letter)))
for ref in sort_by_basename(refs):
docname = ref['docname']
ref_name = basename(docname)
if node.subfolder == 'all':
ref_name += f" ({docname.split('/')[-2]})"
para += add_bullet_point(app, fromdocname, docname, ref_name)
content.append(para)
node.replace_self(content)
def run(self):
self.assert_has_content()
container = nodes.container(
"",
type="tabbed",
new_group="new-group" in self.options,
selected="selected" in self.options,
classes=["tabbed-container"],
)
self.set_source_info(container)
# add label as a rubric (to degrade nicely for non-html outputs)
textnodes, messages = self.state.inline_text(self.arguments[0],
self.lineno)
label = nodes.rubric(self.arguments[0],
*textnodes,
classes=["tabbed-label"])
label["classes"] += self.options.get("class-label", [])
self.add_name(label)
container += label
# add content
content = nodes.container("", is_div=True, classes=["tabbed-content"])
content["classes"] += self.options.get("class-content", [])
self.state.nested_parse(self.content, self.content_offset, content)
container += content
return [container]
def run(self):
set_classes(self.options)
rubric_text = self.arguments[0]
textnodes, messages = self.state.inline_text(rubric_text, self.lineno)
rubric = nodes.rubric(rubric_text, '', *textnodes, **self.options)
self.add_name(rubric)
return [rubric] + messages
def run(self):
set_classes(self.options)
rubric_text = self.arguments[0]
textnodes, messages = self.state.inline_text(rubric_text, self.lineno)
rubric = nodes.rubric(rubric_text, '', *textnodes, **self.options)
self.add_name(rubric)
return [rubric] + messages
def after_contentnode(self, node):
# derived_from:
if (
self.ent_name not in ROOT_TYPES and
self.section != 'data_types'
):
deriv = self.data['derived_from']
xref_node = addnodes.pending_xref(
'', refdomain='cfy', reftype=self.kind,
reftarget=deriv,
modname=None, classname=None,
)
xref_node += nodes.Text(deriv, deriv)
node.append(nodes.paragraph(
'Derived from: ', 'Derived from: ',
xref_node,
))
if 'properties' in self.data:
node.append(nodes.rubric('', 'Properties:'))
props = nodes.definition_list()
node.append(props)
self.generate_properties(props, self.data['properties'])
def process_sampledata_xrefs(app, doctree, fromdocname):
env = app.builder.env
if not hasattr(env, 'all_sampledata_xrefs'):
env.all_sampledata_xrefs = []
for node in doctree.traverse(sampledata_list):
refs = []
for s in env.all_sampledata_xrefs:
if s["keyword"] == node.sampledata_key and not s in refs:
refs.append(s)
content = []
if refs:
list_ref_names = []
para = nodes.paragraph()
para += nodes.rubric('Examples', 'Examples')
for ref in sort_by_basename(refs):
ref_name = ref['basename']
if ref_name in list_ref_names:
ref_name += f" ({ref['docname'].split('/')[-2]})"
list_ref_names.append(ref_name)
para += add_bullet_point(app, fromdocname, ref['docname'],
ref_name)
content.append(para)
node.replace_self(content)
def _doc_widget(self, widgetname):
sec = nodes.section()
sec['ids'].append(widgetname)
# set a title:
sec.append(nodes.subtitle(text=widgetname))
# fetch main documentation
maindoc = factory.doc['blueprint'].get(widgetname, None)
if maindoc is not None:
sec.append(self._rest2node(maindoc))
else:
sec.append(
nodes.paragraph(text='This widget is currently undocumented.'))
# document properties
rub = nodes.rubric(text='Properties')
sec.append(rub)
table = """
+----------+---------+-------------+
| name | default | description |
+==========+=========+=============+
| replace | replace | replace |
+----------+---------+-------------+
"""
table = self._rest2node(table)
table.children[0].children[0].children[4].children = []
rub.append(table)
for prop in self._managed_props_of(widgetname):
table.children[0].children[0].children[4].append(
self._doc_property(prop))
# build table of callables used
rub = nodes.rubric(text='Chains')
sec.append(rub)
table = """\
+------------+----------------+-------------------+---------------+----------+
| extractors | edit renderers | display renderers | preprocessors | builders |
+============+================+===================+===============+==========+
| replace | replace | replace | replace | replace |
+------------+----------------+-------------------+---------------+----------+
"""
table = self._rest2node(table)
rub.append(table)
row = table.children[0].children[0].children[6].children[0]
for col, idx in [(0, 0), (1, 1), (2, 4), (3, 2), (4, 3)]:
row[col].children = []
row[col].append(self._doc_chain(widgetname, idx))
return sec
def _doc_widget(self, widgetname):
sec = nodes.section()
sec['ids'].append(widgetname)
# set a title:
sec.append(nodes.subtitle(text=widgetname))
# fetch main documentation
maindoc = factory.doc['blueprint'].get(widgetname, None)
if maindoc is not None:
sec.append(self._rest2node(maindoc))
else:
sec.append(nodes.paragraph(
text='This widget is currently undocumented.'))
# build table of callables used
rub = nodes.rubric(text='Chains')
sec.append(rub)
table= """
+------------+----------------+---------------+----------+-------------------+
| extractors | edit renderers | preprocessors | builders | display renderers |
+============+================+===============+==========+===================+
| replace | replace | replace | replace | replace |
+------------+----------------+---------------+----------+-------------------+
"""
table = self._rest2node(table)
rub.append(table)
row = table.children[0].children[0].children[6].children[0]
for idx in range(0,5):
row[idx].children = []
row[idx].append(self._doc_chain(widgetname, idx))
# document properties
rub = nodes.rubric(text='Properties')
sec.append(rub)
table= """
+----------+---------+-------------+
| property | default | description |
+==========+=========+=============+
| replace | replace | replace |
+----------+---------+-------------+
"""
table = self._rest2node(table)
table.children[0].children[0].children[4].children = []
rub.append(table)
for prop in self._managed_props_of(widgetname):
table.children[0].children[0].children[4].append(
self._doc_property(prop))
return sec
def get_table(self, items):
table, table_spec, append_row = self.get_tablespec()
for name, description in items:
col1 = ':strong:`' + name + '`'
while description and not description[0].strip():
description.pop(0)
col2 = ' '.join(description)
append_row(col1, col2)
return [nodes.rubric('', 'Enum: %s' % self.name), table]
def get_table(self, items):
table, table_spec, append_row = self.get_tablespec()
for name, description in items:
col1 = ':strong:`' + name + '`'
while description and not description[0].strip():
description.pop(0)
col2 = ' '.join(description)
append_row(col1, col2)
return [nodes.rubric('', 'Enum: %s' % self.name), table]
def annotation_section(self, species, annotation):
map_id = self.get_annotation_id(species, annotation)
target = self.get_target(map_id)
section = nodes.section(ids=[map_id])
section += nodes.title(text=annotation.id)
section += nodes.paragraph(text=annotation.description)
section += nodes.rubric(text="Citations")
section += self.citation_list(annotation)
return [target, section]
def genetic_map_section(self, species, genetic_map):
map_id = self.get_genetic_map_id(species, genetic_map)
target = self.get_target(map_id)
section = nodes.section(ids=[map_id])
section += nodes.title(text=genetic_map.id)
section += nodes.paragraph(text=genetic_map.long_description)
section += nodes.rubric(text="Citations")
section += self.citation_list(genetic_map)
return [target, section]
def dfe_section(self, species, dfe):
dfe_id = self.get_dfe_id(species, dfe)
target = self.get_target(dfe_id)
section = nodes.section(ids=[dfe_id])
section += nodes.title(text=dfe.id)
section += nodes.paragraph(text=dfe.description)
section += nodes.rubric(text="Citations")
section += self.citation_list(dfe)
return [target, section]
def render_simple(self, app, doctree, objs, n1, n2):
if objs:
#ni = nodes.list_item()
ni = nodes.definition_list_item()
rub = nodes.rubric(text=n1)
st = nodes.strong()
st.append(rub)
ren = filebrief_replace_node(app, doctree, n2, objs)
ni.append(st)
ni.append(ren)
return ni
def _downgrade_subsections(section):
children = []
for child in section.children[1:]:
if not isinstance(child, nodes.section):
children += [child]
else:
rubric = nodes.rubric('', child[0][0])
rubric.update_basic_atts(child)
children += [rubric]
children += child.children[1:]
return children
def autosumm_nodes(self, documenter, grouped_documenters, nested):
"""Create the autosummary nodes based on the documenter content
Parameters
----------
documenter: sphinx.ext.autodoc.Documenter
The base (module or class) documenter for which to generate the
autosummary tables of its members
grouped_documenters: dict
The dictionary as it is returned from the
:meth:`AutosummaryDocumenter.get_grouped_documenters` method
nested: bool
If true, autosummary tables will also be created for members.
Returns
-------
dict
a mapping from the objects fullname to the corresponding
autosummary tables of its members. The objects include the main
object of the given `documenter` and the classes that are defined
in it
See Also
--------
AutosummaryDocumenter.get_grouped_documenters, inject_summ_nodes"""
summ_nodes = {}
this_nodes = []
for section, documenters in six.iteritems(grouped_documenters):
items = self.get_items_from_documenters(documenters)
if not items:
continue
node = nodes.rubric()
# create note for the section title (we could also use .. rubric
# but that causes problems for latex documentations)
self.state.nested_parse(ViewList(['**%s**' % section]), 0, node)
this_nodes += node
this_nodes += self.get_table(items)
if nested:
for mdocumenter, check_module in documenters:
if (mdocumenter.objtype == 'class'
and not (check_module
and not mdocumenter.check_module())):
if hasattr(mdocumenter, 'get_grouped_documenters'):
summ_nodes.update(
self.autosumm_nodes(
mdocumenter,
mdocumenter.get_grouped_documenters(),
nested))
summ_nodes[documenter.fullname] = this_nodes
return summ_nodes
def header(item):
"""Creates an Table Header with the Type Name and Documentation"""
nsubtitle = nodes.rubric(text='')
subt = f'{str(item[0])}'
nstrong = nodes.strong(text=subt)
nsubtitle.append(nstrong)
desc = str(item[1].description).split('\n')
ndescription = nodes.paragraph(text='')
for line in desc:
if 'Args' in line:
break
ndescription.append(nodes.Text(f'{line}'))
return nsubtitle, ndescription
def process_readingtime_nodes(app, doctree, fromdocname):
env = app.builder.env
count = 0
for node in doctree.traverse(nodes.paragraph):
tt = node.astext()
count += len(tt.split(" "))
for node in doctree.traverse(ReadingTime):
para = nodes.rubric()
minutes = int(round(count / 200.0))
minutes = max(minutes, 1)
para += nodes.Text("Reading time: {} {}".format(
minutes, 'minute' if minutes == 1 else 'minutes'))
node.replace_self([para])
def make_plugin_section(plugin_group):
elements = []
for item in plugin_group["items"]:
name = item["name"].title() if "SLA" != item["name"] else item["name"]
elements.append(
nodes.subtitle(text="%ss [%s]" % (name, plugin_group["group"])))
for p in _get_plugin_info(item):
elements.append(
nodes.rubric(text="%s [%s]" % (p["name"], item["name"])))
elements.append(nodes.doctest_block(text=p["description"]))
return elements
def make_plugin_section(plugin_group):
elements = []
for item in plugin_group["items"]:
name = item["name"].title() if "SLA" != item["name"] else item["name"]
elements.append(nodes.subtitle(
text="%ss [%s]" % (name, plugin_group["group"])))
for p in _get_plugin_info(item):
elements.append(nodes.rubric(
text="%s [%s]" % (p["name"], item["name"])))
elements.append(nodes.doctest_block(text=p["description"]))
return elements
def run(self):
idb = nodes.make_id("emva1288-" + self.options['section'])
section = nodes.section(ids=[idb])
section += nodes.rubric(text='Emva1288')
lst = nodes.bullet_list()
for k in self.option_spec.keys():
if k not in self.options:
continue
item = nodes.list_item()
item += nodes.strong(text=k + ':')
item += nodes.inline(text=' ' + self.options[k])
lst += item
section += lst
return [section]
def autosumm_nodes(self, documenter, grouped_documenters):
"""Create the autosummary nodes based on the documenter content
Parameters
----------
documenter: sphinx.ext.autodoc.Documenter
The base (module or class) documenter for which to generate the
autosummary tables of its members
grouped_documenters: dict
The dictionary as it is returned from the
:meth:`AutosummaryDocumenter.get_grouped_documenters` method
Returns
-------
dict
a mapping from the objects fullname to the corresponding
autosummary tables of its members. The objects include the main
object of the given `documenter` and the classes that are defined
in it
See Also
--------
AutosummaryDocumenter.get_grouped_documenters, inject_summ_nodes"""
summ_nodes = {}
this_nodes = []
for section, documenters in six.iteritems(grouped_documenters):
items = self.get_items_from_documenters(documenters)
if not items:
continue
node = nodes.rubric()
# create note for the section title (we could also use .. rubric
# but that causes problems for latex documentations)
self.state.nested_parse(
ViewList(['**%s**' % section]), 0, node)
this_nodes += node
this_nodes += self.get_table(items)
for mdocumenter, check_module in documenters:
if (mdocumenter.objtype == 'class' and
not (check_module and not mdocumenter.check_module())):
if hasattr(mdocumenter, 'get_grouped_documenters'):
summ_nodes.update(self.autosumm_nodes(
mdocumenter, mdocumenter.get_grouped_documenters())
)
summ_nodes[documenter.fullname] = this_nodes
return summ_nodes
def render_sub(self, app, doctree, objs, n1, n2):
if objs:
#pni = nodes.list_item()
pni = nodes.paragraph()
pni = nodes.definition_list_item()
prub = nodes.rubric(text=n1)
st = nodes.strong()
st.append(prub)
pni.append(st)
pbl = nodes.bullet_list()
pni.append(pbl)
for (n, be) in objs.iteritems():
ni = nodes.list_item()
prub = nodes.paragraph(text=n2 + n)
pbl.append(ni)
ni.append(prub)
ni.append(be.render(app, doctree))
return pni
def run(self):
clazz = self.arguments[0]
rubric_title = None
rubric_elems = None
rubric_public_elems = None
try:
(module_name, class_name) = clazz.rsplit('.', 1)
m = __import__(module_name, globals(), locals(), [class_name])
c = getattr(m, class_name)
if 'methods' in self.options:
rubric_title = 'Methods'
_, rubric_elems = self.get_members(self.state.document, c,
'method', ['__init__'])
elif 'enums' in self.options:
rubric_title = 'Enums'
_, rubric_elems = self.get_members(self.state.document, c,
'class', None, False, True)
elif 'signals' in self.options:
rubric_title = 'Signals'
_, rubric_elems = self.get_members(self.state.document, c,
'attribute', None, True)
elif 'attributes' in self.options:
rubric_title = 'Attributes'
_, rubric_elems = self.get_members(self.state.document, c,
'attribute', None, False)
if rubric_elems:
rubric_public_elems = list(
filter(lambda e: not e.startswith('_'), rubric_elems))
self.content = [
"~%s.%s" % (clazz, elem) for elem in rubric_public_elems
]
except BaseException as e:
print(str(e))
raise e
finally:
# add the title before the return of the run
ret = super().run()
if rubric_title:
if rubric_public_elems and len(rubric_public_elems) > 0:
rub = nodes.rubric('', rubric_title)
ret.insert(0, rub)
return ret
def run(self):
"""Parse a tabs directive."""
self.assert_has_content()
container = TabContainer("", type="tab", new_set="new-set" in self.options)
self.set_source_info(container)
# Handle the label (non-plain-text variants allowed)
textnodes, messages = self.state.inline_text(self.arguments[0], self.lineno)
label = nodes.rubric(self.arguments[0], *textnodes)
# Handle the content
content = nodes.container("", is_div=True, classes=["tab-content"])
self.state.nested_parse(self.content, self.content_offset, content)
container += label
container += content
return [container]
def footnote_spot(tree: nodes.document) -> Tuple[Element, int]:
"""Find or create a spot to place footnotes.
The function returns the tuple (parent, index)."""
# The code uses the following heuristic:
# a) place them after the last existing footnote
# b) place them after an (empty) Footnotes rubric
# c) create an empty Footnotes rubric at the end of the document
fns = tree.traverse(nodes.footnote)
if fns:
fn = fns[-1]
return fn.parent, fn.parent.index(fn) + 1
for node in tree.traverse(nodes.rubric):
if len(node) == 1 and node.astext() == FOOTNOTES_RUBRIC_NAME:
return node.parent, node.parent.index(node) + 1
doc = tree.traverse(nodes.document)[0]
rub = nodes.rubric()
rub.append(nodes.Text(FOOTNOTES_RUBRIC_NAME))
doc.append(rub)
return doc, doc.index(rub) + 1
def footnote_spot(tree):
"""Find or create a spot to place footnotes.
The function returns the tuple (parent, index)."""
# The code uses the following heuristic:
# a) place them after the last existing footnote
# b) place them after an (empty) Footnotes rubric
# c) create an empty Footnotes rubric at the end of the document
fns = tree.traverse(nodes.footnote)
if fns:
fn = fns[-1]
return fn.parent, fn.parent.index(fn) + 1
for node in tree.traverse(nodes.rubric):
if len(node.children) == 1 and node.children[0].astext() == FOOTNOTES_RUBRIC_NAME:
return node.parent, node.parent.index(node) + 1
doc = tree.traverse(nodes.document)[0]
rub = nodes.rubric()
rub.append(nodes.Text(FOOTNOTES_RUBRIC_NAME))
doc.append(rub)
return doc, doc.index(rub) + 1
def footnote_spot(tree):
"""Find or create a spot to place footnotes.
The function returns the tuple (parent, index)."""
# The code uses the following heuristic:
# a) place them after the last existing footnote
# b) place them after an (empty) Footnotes rubric
# c) create an empty Footnotes rubric at the end of the document
fns = tree.traverse(nodes.footnote)
if fns:
fn = fns[-1]
return fn.parent, fn.parent.index(fn) + 1
for node in tree.traverse(nodes.rubric):
if len(node.children) == 1 and \
node.children[0].astext() == _footnotes_rubric_name:
return node.parent, node.parent.index(node) + 1
doc = tree.traverse(nodes.document)[0]
rub = nodes.rubric()
rub.append(nodes.Text(_footnotes_rubric_name))
doc.append(rub)
return doc, doc.index(rub) + 1
def rubric(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
rubric_text = arguments[0]
textnodes, messages = state.inline_text(rubric_text, lineno)
rubric = nodes.rubric(rubric_text, '', *textnodes, **options)
return [rubric] + messages
def run(self):
return [nodes.rubric(text='Member types')]
def run(self):
return [nodes.rubric(text='Non-member functions')]
def rubric(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
rubric_text = arguments[0]
textnodes, messages = state.inline_text(rubric_text, lineno)
rubric = nodes.rubric(rubric_text, '', *textnodes, **options)
return [rubric] + messages
def run(self):
return [nodes.rubric(text='Example')]