Merge pull request #478 from rackerlabs/argo-workflow-docs-20241113-1

fix: updates argo to mermaid script for new workflow directory structure and layout

.gitignore

@@ -27,3 +27,6 @@ docs/workflows/
 # devbox's envrc
 .envrc
 .direnv
+
+# mkdocs site output
+site/

docs/component-understack-workflows.md

@@ -80,7 +80,7 @@ execute a Workflow.
 Service Account access it needs to run Workflows.
 1. An [Argo Events][argo-events] Sensors and Triggers that
 execute workflows.
-1. [Workflow Templates](./workflows/argo-events.md)
+1. [Workflow Templates](./workflows/enroll-server.md)
 
 ## Containers and Source Code
 

scripts/argo-workflows-to-mkdocs.py

@@ -101,6 +101,7 @@ def main_orig():
 def main():
     if len(sys.argv) < 3:
         print("Usage: python script.py argo-workflows-input-dir mkdocs-output-dir")
+        print("The script will scan for 'workflowtemplates' dir in subdirs")
         sys.exit(1)
 
     input_dir = sys.argv[1]
@@ -128,35 +129,60 @@ def main():
             )
             continue
 
-        workflows = {}
         for workflow_file in workflow_files:
+            workflows = {}
+
             w_yaml = parse_yaml(workflow_file)
-            readme_file = workflow.path + "/docs/README.md"
-            workflow_readme = load_readme(readme_file)
+            workflow_name = w_yaml["metadata"]["name"]
+            workflow_title = (
+                w_yaml["metadata"]
+                .get("annotations", {})
+                .get("workflows.argoproj.io/title", "Title not set in workflow")
+            )
+            workflow_description = (
+                w_yaml["metadata"]
+                .get("annotations", {})
+                .get(
+                    "workflows.argoproj.io/description",
+                    "Description not set in workflow",
+                )
+                .strip("\n")
+            )
+
+            # replace spaces with dashes because we're using workflow_name
+            # as the filename in mkdocs
+            workflow_name.replace(" ", "-")
+
+            workflow_readme = f"## {workflow_title} \n\n {workflow_description}"
+
             if not w_yaml:
                 print(f"Failed to parse {workflow_file}")
                 continue
             w = make_workflow(w_yaml)
             workflows[w.name] = w
 
-        nodes = {}
-        for w in workflows.values():
-            for n in w.nodes:
-                nodes[n.id] = n
-        for w in workflows.values():
-            for n in w.nodes:
-                for t in n.tasks:
-                    if nodes.get(t.ref_node):
-                        nodes[t.ref_node].incoming_count += 1
-                for t in n.steps:
-                    if nodes.get(t.ref_node):
-                        nodes[t.ref_node].incoming_count += 1
-
-        output_file = output_dir + f"/{workflow.name}.md"
-
-        generate_mermaid(
-            workflows.values(), nodes, workflow.name, output_file, workflow_readme
-        )
+            nodes = {}
+            for w in workflows.values():
+                for n in w.nodes:
+                    nodes[n.id] = n
+            for w in workflows.values():
+                for n in w.nodes:
+                    for t in n.tasks:
+                        if nodes.get(t.ref_node):
+                            nodes[t.ref_node].incoming_count += 1
+                    for t in n.steps:
+                        if nodes.get(t.ref_node):
+                            nodes[t.ref_node].incoming_count += 1
+
+            output_file = output_dir + f"/{workflow_name}.md"
+
+            generate_mermaid(
+                workflows.values(),
+                nodes,
+                w_yaml["metadata"]["name"],
+                output_file,
+                workflow_readme,
+            )
 
 
 def make_workflow(w_yaml):
@@ -616,17 +642,18 @@ def generate_mermaid(workflows, nodes, output_name, output_file, workflow_readme
     with open(output_file, "w") as f:
         f.write(f"# {output_name}\n")
         f.write("\n")
-        f.write("# Workflow Diagram\n")
+
+        if workflow_readme:
+            f.write(workflow_readme)
+
+        f.write("\n")
+        f.write("## Workflow Diagram\n")
         f.write("\n")
         f.write("```mermaid\n")
         f.write(mermaid_output)
         f.write("\n")
         f.write("```\n")
         f.write("\n")
-        if workflow_readme:
-            f.write(workflow_readme)
-        else:
-            f.write("This workflow does not have a `docs/README.md` file! :(\n")
 
 
 def parse_depends(depends):
@@ -717,15 +744,6 @@ def parse_or(self):
     return list(dict.fromkeys(parser.term_prefixes))
 
 
-def load_readme(file_path):
-    try:
-        with open(file_path, "r") as stream:
-            return stream.read()
-    except Exception:
-        log.exception("Problem loading README.md file")
-        return None
-
-
 def parse_yaml(file_path):
     with open(file_path, "r") as stream:
         try: