def _example_items(pages, egdocs, context, include=False):
items = []
for egdoc in egdocs:
data = {}
if include:
egdata = pages.json(egdoc["path"], context)
if egdata:
body = egdata.get("body", ())
attrs = egdata.get("attrs", {})
title = functions.first_subblock_of_type(body, "title")
summary = functions.first_subblock_of_type(body, "summary")
data["body"] = body
data["examplefile"] = attrs.get("examplefile")
data["examplefor"] = attrs.get("examplefor")
if title:
data["title"] = title.get("text", ())
if summary:
data["summary"] = summary.get("text", ())
if not data.get("title"):
data["title"] = egdoc.get("title")
if not data.get("summary"):
data["summary"] = egdoc.get("summary")
if not data.get("examplefile"):
data["examplefile"] = egdoc.get("examplefile")
if not data.get("examplefor"):
data["examplefor"] = egdoc.get("examplefor")
data["path"] = egdoc["path"]
data["key"] = egdoc.get("title", "")
items.append(data)
items.sort(key=lambda d: d["key"])
return items
def apply(self, block, context):
path = paths.basepath(context["path"])
if not path.startswith("/nodes/"):
return
# Assume if it doesn't have a parameters section it's not a node
body = block.get("body", ())
parms = functions.first_subblock_of_type(body, "parameters_section")
if not parms:
return
from houdinihelp import path_to_components
from houdinihelp import path_to_nodetype
from houdinihelp import table_to_dir
nodeinfo = path_to_components(path)
if nodeinfo is None:
return
# Fill in missing properties from information in path
attrs = block.setdefault("attrs", {})
if "type" not in attrs:
attrs["type"] = "node"
if "context" not in attrs:
attrs["context"] = table_to_dir[nodeinfo.table]
if "internal" not in attrs:
attrs["internal"] = nodeinfo.corename
if "version" not in attrs:
attrs["version"] = nodeinfo.version
if "namespace" not in attrs:
attrs["namespace"] = nodeinfo.namespace
body = block.get("body", ())
title = functions.first_subblock_of_type(body, "title")
if title is None:
# Get the node label from HOM
nodetype = path_to_nodetype(path)
if nodetype:
title = nodetype.description()
if title:
# Create a fake title block and add it to the beginning of
# the document body
tblock = {"type": "title", "text": [title]}
body.insert(0, tblock)
def _process_example_page(self, block, context, is_node_eg, is_panel_eg):
path = context["path"]
attrs = block.get("attrs", {})
# Example authors are very lax about giving the example documents
# titles; if the document doesn't have a title, make one up from the
# file name
title = functions.first_subblock_of_type(block, "title")
if not title:
name = text_type(paths.barename(path))
body = block.setdefault("body", [])
body.insert(0, {
"type": "title", "indent": 0, "text": [name]
})
# Check for an explicit exampleFor property, otherwise guess it
# from the example's directory tree
if is_node_eg:
block.setdefault("attrs", {})["type"] = "example"
if "exampleFor" in attrs:
egfor = attrs["exampleFor"]
elif "examplefor" in attrs:
egfor = attrs["examplefor"]
else:
egfor = self._node_path_from_example_path(path)
# Attach the list of nodes to the root
block["examplefor"] = egfor
egpath = None
# Check for an explicit exampleFile property, otherwise guess it
# by looking for the example name with an extension
if "exampleFile" in attrs:
egpath = attrs["exampleFile"]
elif "examplefile" in attrs:
egpath = attrs["examplefile"]
elif is_node_eg:
base = paths.basepath(path)
for ext in (".hda", ".otl"):
egpath = base + ext
if context.pages.exists(egpath):
break
elif is_panel_eg:
egpath = self._file_path_from_panel_path(path)
if egpath:
egpath = paths.join(path, egpath)
if context.pages.exists(egpath):
block["examplefile"] = egpath
def getParsedTooltip(url, content):
if content.lstrip().startswith("<"):
# TODO: Pull a tooltip out of raw HTML
return None
path = urlToPath(url)
if not path:
return
pages = get_pages()
json = pages.string_to_json(path, content, postprocess=False)
body = json.get("body", ())
summary = functions.first_subblock_of_type(body, "summary")
if summary:
return functions.string(summary)
def _process_node_page(self, block, context):
path = context["path"]
pages = context.pages
searcher = context.searcher
if not searcher:
return
# Look for an examples section on this page
body = block.setdefault("body", [])
egblock = functions.first_subblock_of_type(body, "examples_section")
if egblock:
found = True
else:
# This page doesn't have an examples section, we have to
# make one
found = False
egblock = {
"type": "examples_section", "role": "section",
"id": "examples", "level": 1,
"text": "Examples",
}
has_egs = False
# Find direct examples
vpath = paths.basepath(path)
egdocs = searcher.documents(examplefor=vpath)
if egdocs:
# Put them in an attribute on the examples section
egblock["examples"] = self._example_items(pages, egdocs, context,
include=True)
has_egs = True
# Find usages
usagedocs = searcher.documents(uses=vpath)
if usagedocs:
# Put them in an attribute on the examples section
egblock["usages"] = self._example_items(pages, usagedocs, context)
has_egs = True
# If we have examples and the page didn't have its own examples
# section, append the one we made to the body
if has_egs and not found:
body.append(egblock)
def _process_load_block(block, context):
pages = context.pages
attrs = block.setdefault("attrs", {})
egpath = attrs.get("path")
egfile = attrs.get("examplefile")
title = functions.string(block.get("text"))
body = block.get("body")
if egpath:
# If the user gave a path to an example description file, load
# it and use it to fill in any missing bits
egsrc = pages.source_path(egpath)
if pages.exists(egsrc):
egdata = pages.json(egpath, context)
egbody = egdata.get("body", [])
# Fill in example file path
if not egfile:
attrs["examplefile"] = egdata.get("examplefile")
# Fill in example text body
if not body and attrs.get("include") == "yes":
block["body"] = egbody
# Fill in example title
if not title:
tb = functions.first_subblock_of_type(egbody, "title")
block["text"] = tb.get("text", [])
def _superclasses(self, pages, methodnames, context, block, history=None):
# Recursively loads the doc pointed to by the block's "superclass"
# attribute and yields a (path, rootblock) pair for each superclass
history = history or set()
attrs = block.get("attrs", {})
superclass = attrs.get("superclass")
if superclass:
path = "/hom/" + superclass.replace(".", "/")
spath = pages.source_path(path)
if pages.exists(spath):
if spath in history:
raise Exception("Circular superclass structure")
else:
history.add(spath)
doc = pages.json(spath, conditional=context.get("conditional"),
postprocess=False)
titleblock = functions.first_subblock_of_type(doc, "title")
if titleblock:
title = functions.string(titleblock.get("text"))
else:
title = superclass
# Find the method items on the superclass
section = functions.subblock_by_id(doc, "methods")
methods = []
if section:
for methblock in functions.find_items(doc, "methods_item"):
text = methblock.get("text")
name = functions.string(text).split("(")[0]
attrs = methblock.get("attrs", {})
body = methblock.get("body", [])
# If this name is in the set of seen methods, it's
# overridden, so we should skip it
if name in methodnames:
continue
methodnames.add(name)
# Copy information about the method into a dict
summary = functions.first_subblock_string(methblock)
methdict = {
"name": name,
"text": text,
"summary": summary,
"more": len(body) > 1,
}
if "status" in attrs:
methdict["status"] = attrs["status"]
methods.append(methdict)
yield {
"path": path,
"title": title,
"methods": methods
}
for x in self._superclasses(pages, methodnames, context, doc,
history):
yield x
