new conventions
This commit is contained in:
@@ -3,13 +3,18 @@
|
||||
# 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 book SRC=../station the whole operation, measured at both ends
|
||||
# make check prove docgen, on a tree it builds itself
|
||||
# make check BOOK=out/book/x prove one book — its own level
|
||||
# make ir SRC=../station extract -> out/ir.json (one step, on its own)
|
||||
# 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 self docgen's book of itself, then check it
|
||||
# make doctor what this machine has
|
||||
#
|
||||
# Every target below is one step of a book and still works alone — that is the
|
||||
# property the book spine exists to preserve, not to replace.
|
||||
#
|
||||
# The pipeline is three commands and they compose, which is the point:
|
||||
#
|
||||
# python3 -m docgen.extractors.python --root SRC -o ir.json
|
||||
@@ -25,14 +30,24 @@ RUN := PYTHONPATH=$(PARENT) $(PY) -m
|
||||
OUT ?= $(HERE)/out
|
||||
SRC ?=
|
||||
SCHEMA ?=
|
||||
OPENAPI ?=
|
||||
HAR ?=
|
||||
STYLE ?= lucid
|
||||
THEME ?=
|
||||
DEPTH ?= 2
|
||||
SCALE ?= 0.55
|
||||
BOOK ?=
|
||||
SLUG ?=
|
||||
# NOT `LANG`: that is the shell's locale variable, so `?=` inherits
|
||||
# en_US.UTF-8 from the environment and --lang rejects it.
|
||||
READER ?= python
|
||||
OVERLAY ?=
|
||||
|
||||
THEME_ARG := $(if $(THEME),--theme $(THEME))
|
||||
SLUG_ARG := $(if $(SLUG),--slug $(SLUG))
|
||||
OVER_ARG := $(if $(OVERLAY),--overlay $(OVERLAY))
|
||||
|
||||
.PHONY: help check ir db code graph index site minimap explore docs view self doctor clean
|
||||
.PHONY: help book check ir db code graph index site minimap explore docs view self doctor clean
|
||||
|
||||
help: ## List every target
|
||||
@echo "docgen — static analysis of a tree, and the artifacts that fall out of it"
|
||||
@@ -42,10 +57,34 @@ help: ## List every target
|
||||
@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 " OPENAPI=spec.yaml an API document HAR=session.har a recording"
|
||||
@echo " BOOK=/path where a book goes, and which book to check"
|
||||
@echo " READER=python|code ast, or tree-sitter SLUG=name what to call the book"
|
||||
@echo " OVERLAY=overlay.json hand-written notebook additions, re-applied every build"
|
||||
@echo " DEPTH=2 how deep to draw"
|
||||
|
||||
check: ## Prove the pipeline, offline, needing nothing installed
|
||||
@$(PY) $(HERE)/selftest.py
|
||||
@echo
|
||||
@echo " Three levels of test, by what they assert about:"
|
||||
@echo " make doctor the machine. Never fails."
|
||||
@echo " make check docgen. Exits 1."
|
||||
@echo " make check BOOK=<dir> that book. Exits 1."
|
||||
|
||||
check: ## Prove docgen (or one book, with BOOK=<dir>)
|
||||
@if [ -n "$(BOOK)" ]; then \
|
||||
$(RUN) $(PKG).book.checks "$(BOOK)"; \
|
||||
else \
|
||||
$(PY) $(HERE)/selftest.py; \
|
||||
fi
|
||||
|
||||
book: ## SRC (or SCHEMA/OPENAPI/HAR) -> one operation, measured at both ends
|
||||
@test -n "$(SRC)$(SCHEMA)$(OPENAPI)$(HAR)" \
|
||||
|| { echo "Error: set SRC=/path/to/tree (or SCHEMA=, OPENAPI=, HAR=)" >&2; exit 1; }
|
||||
@$(RUN) $(PKG).book \
|
||||
$(if $(SRC),--root "$(SRC)" --lang $(READER)) \
|
||||
$(if $(SCHEMA),--schema "$(SCHEMA)") \
|
||||
$(if $(OPENAPI),--openapi "$(OPENAPI)") \
|
||||
$(if $(HAR),--har "$(HAR)") \
|
||||
-o "$(if $(BOOK),$(BOOK),$(OUT)/book)" \
|
||||
--style $(STYLE) $(THEME_ARG) $(SLUG_ARG) $(OVER_ARG)
|
||||
|
||||
ir: ## Extract SRC into OUT/ir.json
|
||||
@test -n "$(SRC)" || { echo "Error: set SRC=/path/to/tree" >&2; exit 1; }
|
||||
@@ -104,15 +143,14 @@ 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)
|
||||
@$(MAKE) --no-print-directory site OUT=$(OUT)
|
||||
@$(MAKE) --no-print-directory minimap OUT=$(OUT)
|
||||
@$(MAKE) --no-print-directory explore OUT=$(OUT)
|
||||
self: ## docgen's book of the widest tree it can see, then check it
|
||||
@$(eval SELF_SRC := $(shell PYTHONPATH=$(PARENT) $(PY) -c "from $(PKG) import reference; \
|
||||
r = reference.root(); print(r if r else '$(HERE)')"))
|
||||
@echo " self-hosting on $(SELF_SRC)"
|
||||
@$(MAKE) --no-print-directory book SRC=$(SELF_SRC) SLUG=self \
|
||||
BOOK=$(OUT)/book/self OUT=$(OUT)
|
||||
@echo
|
||||
@echo " Read $(OUT)/index.md, or open $(OUT)/site/index.html"
|
||||
@$(MAKE) --no-print-directory check BOOK=$(OUT)/book/self
|
||||
|
||||
doctor: ## Report whether this machine can run it
|
||||
@printf 'python : '; $(PY) --version 2>&1 || echo MISSING
|
||||
@@ -120,6 +158,9 @@ doctor: ## Report whether this machine can run it
|
||||
@printf 'tree-sit : '; $(PY) -c 'import tree_sitter, tree_sitter_c_sharp, tree_sitter_typescript; print("ok — C# and TypeScript available")' 2>/dev/null || echo 'absent — Python only. pip install tree_sitter tree_sitter_c_sharp tree_sitter_typescript'
|
||||
@printf 'networkx : '; $(PY) -c 'import networkx; print(networkx.__version__ + " — for lab/ experiments")' 2>/dev/null || echo 'absent — only used in lab/'
|
||||
@printf 'package : %s (from %s)\n' '$(PKG)' '$(PARENT)'
|
||||
@printf 'yaml : '; $(PY) -c 'import yaml; print("ok — needed only to read OpenAPI")' 2>/dev/null || echo 'absent — only used by the OpenAPI reader'
|
||||
@printf 'reference: '; PYTHONPATH=$(PARENT) $(PY) -c "from $(PKG) import reference; print(reference.describe())"
|
||||
|
||||
@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()))"
|
||||
|
||||
Reference in New Issue
Block a user