doc: update

README.md

@@ -0,0 +1,37 @@
+# MARTe Auto Documentation Tool
+
+This tool create a simple yet effective documentation of a MARTe configuration.
+It generates graph for state machines and real time applications, with different level of details. 
+Additionally create a markdown file with all the information condensed.
+
+It automatically generate a standalone `html` and a `pdf` using `pandoc` (markdown to pdf/html) and `dot` (for generate the images for the graph).
+
+It has only standard dependency and the only non standard are the ones needed for parsing the MARTe configurations file and are:
+ - `pyjson` for `json` configuration files
+ - `MARTe` for standard MARTe configuration files
+
+In order to generate the `pdf` and `html` you will also need:
+ - `dot`
+ - `pandoc`
+
+## Usage
+
+
+```
+ausage: autodoc [-h] [--type {json,marte}] [--loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--build BUILD] [--version] [-d DESTINATION] filename
+
+MARTe configuration auto documentation tool
+
+positional arguments:
+  filename              Configuration file to document
+
+options:
+  -h, --help            show this help message and exit
+  --type {json,marte}   Configuration file type (default: `marte`)
+  --loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Logging level (default: `ERROR`)
+  --build BUILD         build output flag
+  --version             show program's version number and exit
+  -d DESTINATION, --destination DESTINATION
+                        Destination folderutodoc -
+```

autodoc/__main__.py

@@ -4,14 +4,12 @@ Main entry point for the MARTe Autodoc project"
 Author: Martino Ferrari
 Email: martinogiordano.ferrari@iter.org
 """
-import json
+
 import logging
 import os
 import sys
 from argparse import ArgumentParser
 
-from MARTe.StandardParser import ParseException, StandardParser
-
 import autodoc
 
 __version__ = "0.0.0"
@@ -36,6 +34,7 @@ def __args__():
         default="ERROR",
         help="Logging level (default: `ERROR`)",
     )
+    parser.add_argument("--build", help="build output flag", default=True)
     parser.add_argument("--version", action="version", version=__version__)
     parser.add_argument(
         "-d", "--destination", help="Destination folder", type=str, default="."
@@ -53,6 +52,8 @@ def main():
         sys.exit(1)
     config = {}
     if args.type == "marte":
+        from MARTe.StandardParser import ParseException, StandardParser
+
         parser = StandardParser()
         try:
             config = parser.parse_file(args.filename)
@@ -65,6 +66,8 @@ def main():
             logging.error(f"Sometihng went wrong with file `{args.filename}`")
             sys.exit(1)
     else:
+        import json
+
         with open(args.filename, "r") as file:
             config = json.load(file)
     if not config:

autodoc/autodoc.py

@@ -53,6 +53,7 @@ def __doc_application__(label, app):
 def document(fname, args, config):
     """Document MARTe object."""
     doc.set_path(os.path.join(args.destination, fname))
+    doc.set_config(args)
     if not os.path.isdir(doc.path()):
         os.mkdir(doc.path())
     now = datetime.now()  # current date and time
@@ -79,11 +80,12 @@ def document(fname, args, config):
     logging.info(f"Saving markdown: {fpath}")
     with open(fpath, "w") as file:
         file.write(mddoc)
-    logging.info(f"Generating html: {outpath}.html")
-    os.system(
-        f"pandoc --css pandoc/styling.css --resource-path={doc.path()} --embed-resource --to html5 -s {fpath} -o {outpath}.html"
-    )
-    logging.info(f"Generating pdf: {outpath}.pdf")
-    os.system(
-        f"pandoc -H pandoc/disable_float.tex --resource-path={doc.path()} -s {fpath} -o {outpath}.pdf"
-    )
+    if doc.build():
+        logging.info(f"Generating html: {outpath}.html")
+        os.system(
+            f"pandoc --css pandoc/styling.css --resource-path={doc.path()} --embed-resource --to html5 -s {fpath} -o {outpath}.html"
+        )
+        logging.info(f"Generating pdf: {outpath}.pdf")
+        os.system(
+            f"pandoc -H pandoc/disable_float.tex --resource-path={doc.path()} -s {fpath} -o {outpath}.pdf"
+        )

autodoc/common.py

@@ -1,6 +1,7 @@
 import logging
 
 __PATH__ = "."
+__CONFIG__ = None
 
 
 def signal(obj, label, type):
@@ -84,3 +85,18 @@ def path():
 def set_path(path):
     global __PATH__
     __PATH__ = path
+
+
+def set_config(config):
+    global __CONFIG__
+    __CONFIG__ = config
+
+
+def config():
+    global __CONFIG__
+    return __CONFIG__
+
+
+def build():
+    global __CONFIG__
+    return str(__CONFIG__.build).upper() == "TRUE"

autodoc/doc_state.py

@@ -620,9 +620,10 @@ def __state_simple_graph__(label, state, app):
 
 def doc_state(label, state, app):
     fname = f"{label[1:]}"
-    src_path = __state_full_graph__(label, state, app)
-    os.system(f"dot -Tsvg -o{os.path.join(doc.path(), fname)}_full.svg {src_path}")
-    src_path = __state_simple_graph__(label, state, app)
-
-    os.system(f"dot -Tsvg -o{os.path.join(doc.path(), fname)}.svg {src_path}")
+    if doc.build():
+        logging.info(f"Building svg grpah {fname}")
+        src_path = __state_full_graph__(label, state, app)
+        os.system(f"dot -Tsvg -o{os.path.join(doc.path(), fname)}_full.svg {src_path}")
+        src_path = __state_simple_graph__(label, state, app)
+        os.system(f"dot -Tsvg -o{os.path.join(doc.path(), fname)}.svg {src_path}")
     return f"![{fname} state]({fname}.svg)" + "{width=100% height=90%}\n"

autodoc/doc_state_machine.py

@@ -38,7 +38,8 @@ def doc_state_machine(name, obj):
     with open(gpath + ".dot", "w") as f:
         f.write(graph)
 
-    logging.info(f"Converting state machine graph: {gpath}.svg")
-    os.system(f"dot -Tsvg -o{gpath}.svg {gpath}.dot")
+    if common.build():
+        logging.info(f"Converting state machine graph: {gpath}.svg")
+        os.system(f"dot -Tsvg -o{gpath}.svg {gpath}.dot")
 
     return f"![{name}]({name}.svg)" + "{width=90%}\n"