Initial

.gitignore

@@ -0,0 +1 @@
+output/

autodoc/__main__.py

@@ -0,0 +1,65 @@
+"""
+Main entry point for the MARTe Autodoc project"
+
+Author: Martino Ferrari
+Email: martinogiordano.ferrari@iter.org
+"""
+from argparse import ArgumentParser
+import logging
+import sys
+import os
+import pprint
+
+from MARTe.StandardParser import StandardParser
+from MARTe.StandardParser import ParseException
+import json
+
+import autodoc
+
+__version__ = "0.0.0"
+
+def __args__():
+  """Parse arguments."""
+  parser = ArgumentParser(
+    prog="autodoc",
+    description="MARTe configuration auto documentation tool",
+  )
+  parser.add_argument("filename", help="Configuration file to document", type=str)
+  parser.add_argument("--type", choices=["json", "marte"], default="marte", help="Configuration file type (default: `marte`)")
+  parser.add_argument("--loglevel", choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], default="ERROR", help="Logging level (default: `ERROR`)")
+  parser.add_argument("--version", action="version", version=__version__)
+  return parser.parse_args()
+
+def main():
+  """Main function."""
+  args = __args__()
+  logging.basicConfig(level=args.loglevel)
+  logging.info(f"AutoDoc v{__version__}")
+  if not os.path.exists(args.filename):
+    logging.error(f"Specified file `{args.filename}` does not exists")
+    sys.exit(1)
+  config = {}
+  if args.type == 'marte':
+    parser = StandardParser()
+    try:
+      config = parser.parse_file(args.filename)
+    except ParseException as e:
+      logging.error(f"Impossible to parse file `{args.filename}` at position ({e.line},{e.col}): {e.msg}`")
+      sys.exit(1)
+    except Exception as e:
+      logging.error(f"Sometihng went wrong with file `{args.filename}`")
+      sys.exit(1)
+  else:
+    with open(args.filename, "r") as file:
+      config = json.load(file)
+  if not config:
+    logging.error(f"Impossible to load configuration `{args.filename}`")
+    sys.exit(1)
+  print(f"# `{os.path.splitext(os.path.basename(args.filename))[0]}` Documentation")
+  for label, obj in config.items():
+    if 'Class' in obj:
+      autodoc.document(label, obj)
+
+if __name__ == '__main__':
+  main()
+

autodoc/autodoc.py

@@ -0,0 +1,135 @@
+"""
+Autodoc functions
+"""
+import logging
+
+
+def __doc_app_state__(state, tab=' │  '):
+  if '+Threads' in state:
+    for i, tname in enumerate(state['+Threads']):
+      if tname[0] == '+':
+        ch = '├─●' if i < len(state['+Threads']) - 1 else '╰─●'
+        print(f'{tab}  {ch} {tname[1:]}')
+
+
+def __doc_state__(label, state, app, full=False):
+  if '+Threads' in state:
+    for tname, obj in state['+Threads'].items():
+      if tname[0] == '+':
+        print()
+        print(f"#### Thread `{tname[1:]}`\n")
+        print(f'Visual representation of the thread `{tname[1:]}`:\n')
+        print('```graphviz')
+        print('digraph structs {')
+        print('  rankdir=LR;')
+        print('  node [shape=record];')
+        datasources = {}
+        if 'Functions' in obj:
+          fns = obj['Functions']
+          for fn in fns:
+            obj = app['+Functions'][f'+{fn}']
+            node = f'  fn{fn} [label="{fn}&#92;n{obj["Class"]}'
+            if full:
+              node += ' | '
+              outputs = ''
+              inputs = ''
+              if "InputSignals" in obj:
+                for i, (l, sig) in enumerate(obj["InputSignals"].items()):
+                  if sig['DataSource'] not in datasources:
+                    datasources[sig['DataSource']] = {}
+                  sn = sig['Alias'] if 'Alias' in sig else l
+                  if sn not in datasources[sig['DataSource']]:
+                    datasources[sig['DataSource']][sn] = [f'fn{fn}:in{i}']
+                  else:
+                    datasources[sig['DataSource']][sn].append(f'fn{fn}:in{i}')
+
+                  if i != 0:
+                    inputs += ' | '
+                  inputs += f'<in{i}> {l} ({sig["Type"]})'
+              if "OutputSignals" in obj:
+                for i, (l, sig) in enumerate(obj["OutputSignals"].items()):
+                  if sig['DataSource'] not in datasources:
+                    datasources[sig['DataSource']] = {}
+                  if l not in datasources[sig['DataSource']]:
+                    datasources[sig['DataSource']][l] = [f'fn{fn}:out{i}']
+                  else:
+                    datasources[sig['DataSource']][l].append(f'fn{fn}:out{i}')
+                  if i != 0:
+                    outputs += ' | '
+                  outputs += f'<out{i}> {l} ({sig["Type"]})'
+              node += '{ { '+inputs+' } | { '+ outputs +' } }"];'
+            else:
+              node += '"];'
+              if "InputSignals" in obj:
+                for i, (l, sig) in enumerate(obj["InputSignals"].items()):
+                  if sig['DataSource'] not in datasources:
+                    datasources[sig['DataSource']] = []
+                  if (fn, 'in') not in datasources[sig['DataSource']]:
+                    datasources[sig['DataSource']].append((fn, 'in'))
+              if "OutputSignals" in obj:
+                for i, (l, sig) in enumerate(obj["OutputSignals"].items()):
+                  if sig['DataSource'] not in datasources:
+                    datasources[sig['DataSource']] = []
+                  if (fn, 'out') not in datasources[sig['DataSource']]:
+                    datasources[sig['DataSource']].append((fn, 'out'))
+            print(node)
+        for l, obj in datasources.items():
+          logging.debug(f"datasource: {l}")
+          ds = app['+Data'][f'+{l}']
+          arrows = ''
+          node = f'  ds{l} [label="{l}&#92;n{ds["Class"]}'
+          if full:
+            node += ' | '
+            for i, s in enumerate(obj):
+              if i > 0:
+                node += " | "
+              node += f'<sig{i}> {s}'
+              for c in obj[s]:
+                if c.split(':')[1].startswith('in'):
+                  arrows += f'  ds{l}:sig{i} -> {c};\n'
+                else:
+                  arrows += f'  {c} -> ds{l}:sig{i};\n'
+          else:
+            for (fn, dir) in obj:
+              if dir == 'in':
+                arrows += f'  ds{l} -> fn{fn};\n'
+              else:
+                arrows += f'  fn{fn} -> ds{l};\n'
+          node += '" color=blue];'
+          print(node)
+          print(arrows)
+        print('}\n```')
+
+def __doc_application__(label, app):
+  print()
+  print(f"## Real-time application: `{label[1:]}`")
+  print()
+  print(f"Below are descrbed the states and threads of the real-time application {label[1:]}.")
+  print("```")
+  print(f'╭{"─"*(len(label)-1)}╮')
+  print(f'│{label[1:]}│')
+  print(f'╰┬{"─"*(len(label)-2)}╯')
+  states = app['+States']
+  for i, (label, obj) in enumerate(states.items()):
+    ch = '├─▷' if i < len(states) - 1 else '╰─▷'
+    tab = ' │  ' if i < len(states) - 1 else '    '
+    if label[0] == '+':
+      print(f' {ch} {label[1:]}')
+      __doc_app_state__(obj, tab)
+  print("```")
+  for label, obj in states.items():
+    if label[0] == '+':
+      print()
+      print(f'### State `{label[1:]}`')
+      __doc_state__(label, obj, app)
+
+
+
+def document(label, obj):
+  """Document MARTe object."""
+  if obj['Class'] == 'RealTimeApplication':
+    __doc_application__(label, obj)
+  if obj['Class'] == 'StateMachine':
+    print()
+    print(f"## State-Machine `{label[1:]}`")
+

pandoc/codeblock-filter.lua

@@ -0,0 +1,35 @@
+-- insprired from https://github.com/pandoc/lua-filters/blob/5686d96/diagram-generator/diagram-generator.lua
+
+local dotPath = os.getenv("DOT") or "dot"
+
+local filetype = "svg"
+local mimetype = "image/svg+xml"
+
+local function graphviz(code, filetype)
+    return pandoc.pipe(dotPath, {"-T" .. filetype}, code)
+end
+
+function CodeBlock(block)
+    local converters = {
+        graphviz = graphviz,
+    }
+
+    local img_converter = converters[block.classes[1]]
+    if not img_converter then
+      return nil
+    end
+
+    local success, img = pcall(img_converter, block.text, filetype)
+
+    if not success then
+        io.stderr:write(tostring(img))
+        io.stderr:write('\n')
+        error 'Image conversion failed. Aborting.'
+    end
+
+    return pandoc.RawBlock('html', img)
+end
+
+return {
+    {CodeBlock = CodeBlock},
+}