def main():
long_description = """
Provide documentation for modules, actors, and components.
"""
default_format = 'compact' if sys.argv[0].endswith('csdocs') else 'detailed'
argparser = argparse.ArgumentParser(description=long_description)
group = argparser.add_mutually_exclusive_group()
group.add_argument('what', metavar='<actor or module>', type=str, nargs='?', default='',
help='What to look up documentation for, if empty show top level documentation')
group.add_argument('--all', action='store_const', const=True, default=False,
help='Generate complete actor documentation in Markdown format')
argparser.add_argument('--format', default=default_format, choices=['detailed', 'compact', 'raw'],
help='Options "detailed" and "compact" returns Markdown-formatted text,'
' while "raw" returns a JSON-formatted representation that can be'
' used to generated the documentation in other formats.')
args = argparser.parse_args()
store = DocumentationStore()
if args.all:
all_docs()
else:
if args.format == 'raw':
print json.dumps(store.help_raw(args.what))
else:
print store.help(args.what, args.format == 'compact')
def _lookup(node, issue_tracker):
if _is_local_component(node.actor_type):
comps = query(_root(node), kind=ast.Component, attributes={'name':node.actor_type})
if not comps:
reason = "Missing local component definition: '{}'".format(node.actor_type)
issue_tracker.add_error(reason, node)
return {'is_known': False}
comp = comps[0]
metadata = {
'is_known': True,
'name': comp.name,
'type': 'component',
'inputs': comp.inports,
'outputs': comp.outports,
'args':{
'mandatory':comp.arg_names,
'optional':{}
},
'definition': comp.children[0]
}
else:
metadata = DocumentationStore().metadata(node.actor_type)
if not metadata['is_known']:
reason = "Not validating actor type: '{}'".format(node.actor_type)
issue_tracker.add_warning(reason, node)
return metadata
def __init__(self, cs_info):
super(Checker, self).__init__()
self.ds = DocumentationStore()
self.cs_info = cs_info
self.local_actors = {}
self.errors = []
self.warnings = []
self.check()
def handle_get_actor_doc(self, handle, connection, match, data, hdr):
""" Query ActorStore for documentation
"""
path = match.group(1)
what = '.'.join(path.strip('/').split('/'))
ds = DocumentationStore()
data = ds.help_raw(what)
self.send_response(handle, connection, json.dumps(data))
def __init__(self, cs_info):
super(Checker, self).__init__()
self.ds = DocumentationStore()
self.cs_info = cs_info
self.constants = self.cs_info['constants']
self.comp_defs = self.cs_info['components']
self.errors = []
self.warnings = []
self.check()
def all_docs(what=None):
ds = DocumentationStore()
raw = ds.help_raw(what)
print ds.help(what)
for actor in raw.get('actors', []):
print ds.help(what + '.' + actor)
for module in raw.get('modules', []):
all_docs(module)
class ActorViz(Viz):
"""docstring for ActorViz"""
docstore = DocumentationStore()
def __init__(self, name, actor_type, args, **dummy):
super(ActorViz, self).__init__()
self.type_color = 'lightblue'
self.name = name
self.args = args
self.actor_type = actor_type
doc = self.docstore.help_raw(actor_type)
self.set_ports(doc)
def set_ports(self, doc):
inports = [p for p, _ in doc['inputs']]
outports = [p for p, _ in doc['outputs']]
inlen = len(inports)
outlen = len(outports)
self.portrows = max(inlen, outlen)
self.inports = inports + [''] * (self.portrows - inlen)
self.outports = outports + [''] * (self.portrows - outlen)
def __str__(self):
lines = []
lines.append('{0} [label=<'.format(_refname(self.name)))
lines.append(
'<TABLE BORDER="1" CELLBORDER="0" CELLSPACING="0" CELLPADDING="1">'
)
# Name
lines.append('<TR><TD bgcolor="{1}" COLSPAN="3">{0}</TD></TR>'.format(
self.name, self.type_color))
# Class
lines.append('<TR><TD COLSPAN="3">{0}</TD></TR>'.format(
self.actor_type))
is_first = True
for inport, outport in zip(self.inports, self.outports):
inref = ' bgcolor="lightgrey" PORT="{0}_in"'.format(
inport) if inport else ''
outref = ' bgcolor="lightgrey" PORT="{0}_out"'.format(
outport) if outport else ''
if is_first:
is_first = False
middle = '<TD ROWSPAN="{0}"> </TD>'.format(self.portrows)
else:
middle = ''
lines.append(
'<TR><TD{0} align="left">{1}</TD>{4}<TD{2} align="right">{3}</TD></TR>'
.format(inref, inport, outref, outport, middle))
lines.append('</TABLE>>];')
return '\n'.join(lines)
def handle_get_actor_doc(self, handle, connection, match, data, hdr):
"""
GET /actor_doc {path}
Get documentation in 'raw' format for actor or module at {path}
Path is formatted as '/{module}/{submodule}/ ... /{actor}'.
If {path} is empty return top-level documentation.
See DocumentStore help_raw() for details on data format.
Response status code: OK
Response: dictionary with documentation
"""
path = match.group(1)
what = '.'.join(path.strip('/').split('/'))
ds = DocumentationStore()
what = None if not what else what
data = ds.help_raw(what)
self.send_response(handle, connection, data)
def _init_metadata(self):
def gather_actors(module):
# Depth first
l = []
for m in d.modules(module):
l = l + gather_actors(m)
actors = d.actors(module)
if module:
# Add namespace
actors = ['.'.join([module, a]) for a in actors]
return l + actors
d = DocumentationStore()
metadata = {}
actors = gather_actors('')
for actor in actors:
parts = actor.split('.')
x = metadata
for p in parts[:-1]:
x = x.setdefault(p, {})
x[parts[-1]] = d.metadata(actor)
self.metadata = metadata
import visitor
import astnode as ast
from codegen import calvin_astgen, query
from parser import calvin_parse
from calvin.actorstore.store import DocumentationStore
_docstore = DocumentationStore()
def _refname(name):
return name.replace(':', '_')
def _lookup_definition(actor_type, root):
if '.' in actor_type:
doc = _docstore.help_raw(actor_type)
if not doc['name']:
return ([], [], '')
t = doc['type']
inports = [p for p,_ in doc['inputs']]
outports = [p for p,_ in doc['outputs']]
else:
t = 'component'
comps = query(root, kind=ast.Component, attributes={'name':actor_type}, maxdepth=2)
if not comps:
return ([], [], '')
inports, outports = comps[0].inports, comps[0].outports
return (inports, outports, t)
#
def setUp(self):
self.ds = DocumentationStore()
