From 1bf403a339833d6b9ae15b1531e0243b8ba24374 Mon Sep 17 00:00:00 2001 From: Ferrari Martino Giordano Date: Wed, 20 Mar 2024 16:06:04 +0100 Subject: [PATCH] doc: update --- README.md | 37 ++++++++++++++++++++++++++++++++++++ autodoc/__main__.py | 9 ++++++--- autodoc/autodoc.py | 18 ++++++++++-------- autodoc/common.py | 16 ++++++++++++++++ autodoc/doc_state.py | 11 ++++++----- autodoc/doc_state_machine.py | 5 +++-- 6 files changed, 78 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index e69de29..dd5387e 100644 --- a/README.md +++ b/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 - +``` diff --git a/autodoc/__main__.py b/autodoc/__main__.py index dbc9de4..05ee5f6 100644 --- a/autodoc/__main__.py +++ b/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: diff --git a/autodoc/autodoc.py b/autodoc/autodoc.py index fb1cdeb..0874627 100644 --- a/autodoc/autodoc.py +++ b/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" + ) diff --git a/autodoc/common.py b/autodoc/common.py index c7a7918..42498d8 100644 --- a/autodoc/common.py +++ b/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" diff --git a/autodoc/doc_state.py b/autodoc/doc_state.py index de2aa4b..66463ac 100644 --- a/autodoc/doc_state.py +++ b/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" diff --git a/autodoc/doc_state_machine.py b/autodoc/doc_state_machine.py index 2d45e91..d41678c 100644 --- a/autodoc/doc_state_machine.py +++ b/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"