docs: rework statemachine docs generation

metal-toolbox · May 4, 2023 · cc26290 · cc26290
1 parent 87f76fc
commit cc26290
Show file tree

Hide file tree

Showing 4 changed files with 74 additions and 23 deletions.
diff --git a/Makefile b/Makefile
@@ -14,6 +14,9 @@ lint:
 test:
 	CGO_ENABLED=0 go test -timeout 1m -v -covermode=atomic ./...
 
+build:
+	go build -o flasher
+
 ## build osx bin
 build-osx:
 ifeq ($(GO_VERSION), 0)
@@ -57,14 +60,8 @@ push-image:
 
 
 ## generate statemachine graphs and docs
-docs: build-osx
-	./flasher export statemachine --action | dot -Tsvg  > ./docs/statemachine/action_sm.svg
-	./flasher export statemachine --task | dot -Tsvg  > ./docs/statemachine/task_sm.svg
-	./flasher export statemachine --task --json > ./docs/statemachine/task-statemachine.json
-	./flasher export statemachine --action --json > ./docs/statemachine/action-statemachine.json
-	./docs/statemachine/generate_action_sm_docs.sh
-	./docs/statemachine/generate_task_sm_docs.sh
-
+docs: build
+	./docs/statemachine/generate.sh
 
 # https://gist.github.com/prwhite/8168133
 # COLORS

diff --git a/docs/statemachine/generate.sh b/docs/statemachine/generate.sh
@@ -0,0 +1,63 @@
+#!/bin/sh
+
+set -e
+
+taskSMDoc="docs/statemachine/README-task-statemachine.md"
+taskSMJSON="docs/statemachine/task-statemachine.json"
+
+actionSMDoc="docs/statemachine/README-action-statemachine.md"
+actionSMJSON="docs/statemachine/action-statemachine.json"
+
+## generate Task statemachine mermaid graph and docs
+
+echo "generate task statemachine docs..."
+
+
+echo "# Flasher task state machine" > $taskSMDoc
+echo " " >> $taskSMDoc
+echo "The Task statemachine plans and executes Actions (sub-statemachines) to install firmware." >> $taskSMDoc
+echo " " >> $taskSMDoc
+echo "Note: The Task statemachine plans and and executes [Action sub-state machine(s)]($actionSMDoc) for each firmware being installed." >> $taskSMDoc
+echo " " >> $taskSMDoc
+
+echo '```mermaid' >> $taskSMDoc
+./flasher export-statemachine --task >> $taskSMDoc
+echo '```' >> $taskSMDoc
+
+
+## generate state transition docs
+
+./flasher export-statemachine --task --json > $taskSMJSON
+
+echo "## Task statemachine transitions" >> $taskSMDoc
+echo " " >> $taskSMDoc
+
+./docs/statemachine/generate_task_sm_docs.sh $taskSMJSON $taskSMDoc
+
+
+echo "generate task action sub-statemachine docs..."
+
+
+## generate action statemachine mermaid graph and docs
+
+
+echo "# Flasher task action sub-state machine(s)" > $actionSMDoc
+echo " " >> $actionSMDoc
+echo "The task Actions (sub-statemachines) are executed by the Task statemachine." >> $actionSMDoc
+echo " " >> $actionSMDoc
+echo "Note: Note each firmware to be installed is one action state machine." >> $actionSMDoc
+echo " " >> $actionSMDoc
+
+echo '```mermaid' >> $actionSMDoc
+./flasher export-statemachine --action >> $actionSMDoc
+echo '```' >> $actionSMDoc
+
+
+## generate state transition docs
+
+./flasher export-statemachine --action --json > $actionSMJSON
+
+echo "## Task Action (sub-statemachine) transitions" >> $actionSMDoc
+echo " " >> $actionSMDoc
+
+./docs/statemachine/generate_action_sm_docs.sh $actionSMJSON $actionSMDoc
diff --git a/docs/statemachine/generate_action_sm_docs.sh b/docs/statemachine/generate_action_sm_docs.sh
@@ -3,12 +3,12 @@
 #
 # script adapted from https://github.com/omertuc/assisted-service/tree/statemachine/cmd/graphstatemachine
 #
-set -euxo pipefail
+set -euo pipefail
 
 SCRIPT_DIR="./docs/statemachine"
 
-JSON="${SCRIPT_DIR}"/action-statemachine.json
-OUT_FILE="${SCRIPT_DIR}"/README-action-statemachine.md
+JSON="$1"
+OUT_FILE="$2"
 
 echo Compiling and running go state machine doc JSON dump...
 #go run "${SCRIPT_DIR}"/main.go | jq >"${JSON}"
@@ -91,12 +91,6 @@ function github_markdown_linkify() {
         | "[\($name)](#\(.))"
     ' -r
 }
-
-echo "# Flasher task action sub-statemachine" >"${OUT_FILE}"
-
-echo "The Action sub-statemachine(s) is executed to install firmware for each component." >>"${OUT_FILE}"
-echo "" >>"${OUT_FILE}"
-
 echo Generating table of contents...
 
 echo "## Table of Contents" >>"${OUT_FILE}"

diff --git a/docs/statemachine/generate_task_sm_docs.sh b/docs/statemachine/generate_task_sm_docs.sh
@@ -3,12 +3,12 @@
 #
 # script adapted from https://github.com/omertuc/assisted-service/tree/statemachine/cmd/graphstatemachine
 #
-set -euxo pipefail
+set -euo pipefail
 
 SCRIPT_DIR="./docs/statemachine"
 
-JSON="${SCRIPT_DIR}"/task-statemachine.json
-OUT_FILE="${SCRIPT_DIR}"/README-task-statemachine.md
+JSON="$1"
+OUT_FILE="$2"
 
 echo Compiling and running go state machine doc JSON dump...
 #go run "${SCRIPT_DIR}"/main.go | jq >"${JSON}"
@@ -92,10 +92,7 @@ function github_markdown_linkify() {
     ' -r
 }
 
-echo "# Flasher task state machine" >"${OUT_FILE}"
 
-echo "The Task statemachine plans and executes Action (sub-statemachines) to install firmware." >>"${OUT_FILE}"
-echo "" >>"${OUT_FILE}"
 
 echo Generating table of contents...