docgen iter 2

soleprint/atlas2/docgen/Makefile

@@ -0,0 +1,90 @@
+# docgen — code to diagram, and to everything else the IR can feed.
+#
+# Derived from where this file sits, so the folder can be copied anywhere and
+# renamed and still work. The logic lives in the Python, never here.
+#
+#   make check                     prove it, on a tree it builds itself
+#   make ir SRC=../station         extract -> out/ir.json
+#   make graph                     out/ir.json -> out/graph.svg
+#   make index                     out/ir.json -> out/index.md
+#   make self                      run the whole pipeline over soleprint itself
+#   make doctor                    what this machine has
+#
+# The pipeline is three commands and they compose, which is the point:
+#
+#   python3 -m docgen.extractors.python --root SRC -o ir.json
+#   python3 -m docgen.ops ir.json --overview -o view.json
+#   python3 -m docgen.emitters dot view.json -o graph.svg --theme dark
+
+HERE   := $(patsubst %/,%,$(dir $(abspath $(lastword $(MAKEFILE_LIST)))))
+PKG    := $(notdir $(HERE))
+PARENT := $(patsubst %/,%,$(dir $(HERE)))
+PY     ?= python3
+RUN    := PYTHONPATH=$(PARENT) $(PY) -m
+
+OUT    ?= $(HERE)/out
+SRC    ?=
+SCHEMA ?=
+STYLE  ?= lucid
+THEME  ?=
+DEPTH  ?= 2
+
+THEME_ARG := $(if $(THEME),--theme $(THEME))
+
+.PHONY: help check ir db graph index view self doctor clean
+
+help:  ## List every target
+	@echo "docgen — static analysis of a tree, and the artifacts that fall out of it"
+	@echo
+	@grep -E '^[a-z-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+	  | awk 'BEGIN{FS=":.*?## "}{printf "  \033[1m%-10s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@echo "  SRC=/path/to/tree     what to read           OUT=/path   where output goes"
+	@echo "  SCHEMA=schema.json    a database instead     STYLE=lucid THEME=dark|lucid"
+	@echo "  DEPTH=2               how deep to draw"
+
+check:  ## Prove the pipeline, offline, needing nothing installed
+	@$(PY) $(HERE)/selftest.py
+
+ir:  ## Extract SRC into OUT/ir.json
+	@test -n "$(SRC)" || { echo "Error: set SRC=/path/to/tree" >&2; exit 1; }
+	@mkdir -p $(OUT)
+	@$(RUN) $(PKG).extractors.python --root "$(SRC)" -o $(OUT)/ir.json
+	@$(RUN) $(PKG).ir $(OUT)/ir.json
+
+db:  ## Extract a graphgen-compatible SCHEMA into OUT/ir.json
+	@test -n "$(SCHEMA)" || { echo "Error: set SCHEMA=/path/to/schema.json" >&2; exit 1; }
+	@mkdir -p $(OUT)
+	@$(RUN) $(PKG).extractors --schema "$(SCHEMA)" -o $(OUT)/ir.json
+	@$(RUN) $(PKG).ir $(OUT)/ir.json
+
+view:  ## OUT/ir.json -> OUT/view.json, the default view for its source type
+	@$(RUN) $(PKG).ops $(OUT)/ir.json --overview -o $(OUT)/view.json
+
+graph: view  ## OUT/view.json -> whatever its structure asks for
+	@$(RUN) $(PKG).emitters auto $(OUT)/view.json -o $(OUT) \
+	  --style $(STYLE) $(THEME_ARG)
+
+index:  ## OUT/ir.json -> OUT/index.md and OUT/sidebar.json
+	@$(RUN) $(PKG).emitters index $(OUT)/ir.json -o $(OUT)/index.md
+	@$(RUN) $(PKG).emitters index $(OUT)/ir.json -o $(OUT)/sidebar.json
+
+self:  ## Run the whole pipeline over soleprint itself — the honest end-to-end check
+	@$(MAKE) --no-print-directory ir SRC=$(PARENT)/.. OUT=$(OUT)
+	@$(MAKE) --no-print-directory index OUT=$(OUT)
+	@$(MAKE) --no-print-directory graph OUT=$(OUT)
+	@echo
+	@echo "  Read $(OUT)/index.md — it should read like the system."
+
+doctor:  ## Report whether this machine can run it
+	@printf 'python   : '; $(PY) --version 2>&1 || echo MISSING
+	@printf 'dot      : '; (dot -V 2>&1) || echo 'MISSING — sudo apt install graphviz (only to render)'
+	@printf 'package  : %s (from %s)\n' '$(PKG)' '$(PARENT)'
+	@printf 'styles   : '; $(RUN) $(PKG).style 2>/dev/null \
+	  || $(RUN) $(PKG) 2>/dev/null \
+	  || PYTHONPATH=$(PARENT) $(PY) -c "from $(PKG).style import Style; print(', '.join(Style.available()))"
+	@PYTHONPATH=$(PARENT) $(PY) -c "import $(PKG).ir, $(PKG).emitters.dot, $(PKG).ops" >/dev/null 2>&1 \
+	  && echo 'import   : ok' || echo 'import   : FAILED — is the folder intact?'
+
+clean:  ## Delete OUT. Nothing else is ever written to
+	@rm -rf "$(OUT)" && echo "Removed $(OUT)"