def formatDeclarationPage(self, moduleName, name, method, item):
parentURI = self.renderer.makeURI(item.module)
trailTitle = self.formatTrailAsTitle(moduleName+"."+name)
itemDocTree = method(moduleName, name, item)
return nodes.section('',
trailTitle,
nodes.paragraph('', '',
nodes.Text("For examples and more explanations, see the "),
nodes.reference('', 'module level docs.', refuri=parentURI)
),
nodes.transition(),
nodes.section('', *itemDocTree),
)
def horizontal_rule(self):
transition_node = nodes.transition()
self.current_node.append(transition_node)
def transition(node):
"""
An <hr> tag in html. This has no children
"""
return nodes.transition()
def horizontal_rule(self):
self.current_node.append(nodes.transition())
def render_hr(self, token):
node = nodes.transition()
self.add_line_and_source_path(node, token)
self.current_node.append(node)
def render_hr(self, token: SyntaxTreeNode) -> None:
node = nodes.transition()
self.add_line_and_source_path(node, token)
self.current_node.append(node)
def render(self, tokens: List[Token], options, env: AttrDict):
"""Run the render on a token stream.
:param tokens: list on block tokens to render
:param options: params of parser instance
:param env: the environment sandbox associated with the tokens,
containing additional metadata like reference info
"""
self.setup_render(options, env)
# propagate line number down to inline elements
for token in tokens:
if token.map:
# For docutils we want 1 based line numbers (not 0)
token.map = [token.map[0] + 1, token.map[1] + 1]
for child in token.children or []:
child.map = token.map
# nest tokens
nested_tokens = nest_tokens(tokens)
# move footnote definitions to env
self.env.setdefault("foot_refs", {})
new_tokens = []
for nest_token in nested_tokens:
if nest_token.type == "footnote_reference_open":
label = nest_token.meta["label"]
self.env["foot_refs"].setdefault(label, []).append(nest_token)
else:
new_tokens.append(nest_token)
nested_tokens = new_tokens
# render
for i, nest_token in enumerate(nested_tokens):
# skip hidden?
if f"render_{nest_token.type}" in self.rules:
self.rules[f"render_{nest_token.type}"](nest_token)
else:
self.create_warning(
f"No render method for: {nest_token.type}",
line=token_line(nest_token, default=0),
subtype="render",
append_to=self.current_node,
)
# log warnings for duplicate reference definitions
# "duplicate_refs": [{"href": "ijk", "label": "B", "map": [4, 5], "title": ""}],
for dup_ref in self.env.get("duplicate_refs", []):
self.create_warning(
f"Duplicate reference definition: {dup_ref['label']}",
line=dup_ref["map"][0] + 1,
subtype="ref",
append_to=self.document,
)
if not self.config.get("output_footnotes", True):
return self.document
# we don't use the foot_references stored in the env
# since references within directives/roles will have been added after
# those from the initial markdown parse
# instead we gather them from a walk of the created document
foot_refs = OrderedDict()
for refnode in self.document.traverse(nodes.footnote_reference):
if refnode["refname"] not in foot_refs:
foot_refs[refnode["refname"]] = True
if foot_refs and self.config.get("myst_footnote_transition", False):
self.current_node.append(nodes.transition(classes=["footnotes"]))
for footref in foot_refs:
foot_ref_tokens = self.env["foot_refs"].get(footref, [])
if len(foot_ref_tokens) > 1:
self.create_warning(
f"Multiple footnote definitions found for label: '{footref}'",
subtype="footnote",
append_to=self.current_node,
)
if len(foot_ref_tokens) < 1:
self.create_warning(
f"No footnote definitions found for label: '{footref}'",
subtype="footnote",
append_to=self.current_node,
)
else:
self.render_footnote_reference_open(foot_ref_tokens[0])
return self.document
def visit_hr(self, node):
return nodes.transition()
def visit_thematic_break(self, _):
self.current_node.append(nodes.transition())
def visit_thematic_break(self, _):
self.current_node.append(nodes.transition())
def horizontal_rule(self):
transition_node = nodes.transition()
self.current_node.append(transition_node)
def formatModulePage(self, moduleName, module, components, prefabs, classes, functions):
trailTitle = self.formatTrailAsTitle(moduleName)
moduleDocTree = self.docString(module.doc, main=True)
testsTree = self.formatTests(moduleName)
while len(testsTree.children)>0:
node=testsTree.children[0]
testsTree.remove(node)
moduleTree.append(node)
if self.config.promoteModuleTitles and \
len(moduleDocTree.children)>=1 and \
isinstance(moduleDocTree.children[0], nodes.title):
theTitle = moduleDocTree.children[0]
moduleDocTree.remove(theTitle)
promotedTitle = [ theTitle ]
else:
promotedTitle = []
toc = self.buildTOC(moduleDocTree, depth=self.config.tocDepth)
allDeclarations = []
declarationTrees = []
for (name,component) in components:
cTrail = self.formatTrail(moduleName+"."+name)
declarationTrees.append((
name,
nodes.container('',
nodes.title('','', *cTrail.children),
self.formatComponent(moduleName,name,component)
)
))
for (name,prefab) in prefabs:
pTrail = self.formatTrail(moduleName+"."+name)
declarationTrees.append((
name,
nodes.container('',
nodes.title('','', *pTrail.children),
self.formatPrefab(moduleName,name,prefab)
)
))
for (name,cls) in classes:
cTrail = self.formatTrail(moduleName+"."+name)
declarationTrees.append((
name,
nodes.container('',
nodes.title('','', *cTrail.children),
self.formatClass(moduleName,name,cls)
)
))
for (name,function) in functions:
fTrail = self.formatTrail(moduleName+"."+name)
declarationTrees.append((
name,
nodes.container('',
nodes.title('','', *fTrail.children),
self.formatFunction(moduleName,name,function)
)
))
declarationTrees.sort() # sort by name
concatenatedDeclarations=[]
for (name,tree) in declarationTrees:
concatenatedDeclarations.extend(tree)
componentListTree = self.declarationsList( moduleName, components, prefabs, classes, functions )
if len(module.listAllModules()) > 0:
subModuleIndex = self.generateIndex(moduleName,module,self.config.treeDepth)
else:
subModuleIndex = []
return nodes.container('',
nodes.section('',
trailTitle,
),
nodes.section('',
* promotedTitle + \
[ componentListTree] + \
subModuleIndex + \
[ toc ]
),
moduleDocTree,
nodes.transition(),
nodes.section('', *concatenatedDeclarations),
)
def horizontal_rule(self):
self.current_node.append(nodes.transition())
def run(self, reader: LineReader, document: Element) -> bool:
reader.readline()
document += nodes.transition()
return True
def transition(node):
"""
An <hr> tag in html. This has no children
"""
return nodes.transition()
def run(self):
text = ' '.join(self.arguments)
title_nodes, _ = self.state.inline_text(text, self.lineno)
transition_node = nodes.transition('', *title_nodes)
transition_node['classes'] += ['m-transition']
return [transition_node]
