subplot 0.13.0

tools for specifying, documenting, and implementing automated acceptance tests for systems and software
Documentation
# Build Subplot and its documentation and run its tests.
#
# The "install_test" target installs the subplot binary so that
# $(SUBPLOT) refers to it. This lets us run Subplot without invoking
# "cargo run" every time. This means we invoke in a way that's more
# natural and have to jump through fewer hoops. Also the binary can be
# run from Python tests directly.
#

# Set this to build offline: --offline.
OFFLINE =

# Set this to limit the tests run by the Rust test suite or the test
# program generated by Subplot. You can override this on the command
# line: "make TESTS=foo tests subplots"
TESTS = 

SUBPLOT_DIR = $(abspath inst)
SUBPLOT = $(SUBPLOT_DIR)/subplot --resources $(abspath share)

all: tooling shell rust test subplots doc

# Check that required tooling is available.
tooling:
	which cargo
	which dot
	which plantuml
	which python3
	which rustc
	which rustfmt
	which tidy

# Check shell scripts for common problems.
shell: tooling
	if which shellcheck; then shellcheck *.sh; fi

# Run clippy and tests for Rust code.
rust: tooling
	if cargo clippy --version; then \
	    cargo clippy --locked $(OFFLINE) --workspace --all-targets -- -Dwarnings && \
		cd examples/seq && cargo clippy --workspace --all-targets -- -Dwarnings; \
	fi

# Run all tests, both Python and Rust.
test: install_test
	cd share/python/template && python3 context_tests.py
	cd share/python/template && python3 encoding_tests.py
	env SUBPLOT_DIR="$(SUBPLOT_DIR)" cargo test --workspace -- $(TESTS)

# Install the subplot binary in a place where we run it from. After
# this target has completed, $(SUBPLOT) will expand to the binary we
# will use for tests.
#
# We use "cargo install" to have a known location, rather than trying
# to determine where "cargo build" puts the binary.
install_test: tooling
	rm -rf "$(SUBPLOT_DIR)"
	cargo install --locked $(OFFLINE) --path=bin --root="$(SUBPLOT_DIR)" --debug
	mv "$(SUBPLOT_DIR)"/bin/* "$(SUBPLOT_DIR)"
	rm -rf "$(SUBPLOT_DIR)"/.crate*  "$(SUBPLOT_DIR)"/bin

# Generate code from and run Subplots.
subplots: install_test
	$(SUBPLOT) codegen subplot.subplot -o test.py --template python
	rm -f test.log
	python3 test.py --log test.log --env SUBPLOT_DIR=$(SUBPLOT_DIR) $(TESTS)

	cd examples/muck && $(SUBPLOT) codegen muck.subplot --run --output test.py
	if [ "$(OFFLINE)" = "" ] ; then \
		cd examples/website && \
		$(SUBPLOT) codegen website.subplot --run --output test.py; \
	fi
	cd examples/seq && cargo test -- $(TESTS)

# Build documentation and move built documentation from next to
# subplot to the "docs" directory, so that they can easily be
# published somewhere. This is simpler than building the docs so they
# land in their final location directly.
doc: docgen libdocs userguide
	mkdir -p doc/libdocs
	for x in subplot.html tests/subplots/common/*.html examples/*/*.html book/*.html; do if [ -e "$$x" ]; then mv "$$x" doc; fi; done
	for x in $(SUBPLOT_DIR)/*.html; do if [ -e "$$x" ]; then mv "$$x" doc/libdocs/; fi; done

docgen: install_test
	$(SUBPLOT) docgen subplot.subplot -o subplot.html
	$(SUBPLOT) docgen tests/subplots/common/files.subplot -o tests/subplots/common/files.html
	$(SUBPLOT) docgen tests/subplots/common/runcmd.subplot -o tests/subplots/common/runcmd.html
	cd examples/muck && $(SUBPLOT)/subplot docgen muck.subplot -o muck.html
	cd examples/website && $(SUBPLOT) docgen website.subplot -o website.html
	cd examples/seq && $(SUBPLOT) docgen seq.subplot -o seq.html

libdocs: install_test
	$(SUBPLOT) libdocgen lib/runcmd.yaml --output $(SUBPLOT_DIR)/runcmd.md
	if which pandoc>/dev/null; then pandoc --toc --standalone --self-contained --metadata "title=lib/runcmd"  --output $(SUBPLOT_DIR)/runcmd.html $(SUBPLOT_DIR)/runcmd.md; fi

	$(SUBPLOT) libdocgen lib/files.yaml --output $(SUBPLOT_DIR)/files.md
	if which pandoc>/dev/null; then pandoc --toc --standalone --self-contained --metadata "title=lib/files"  --output $(SUBPLOT_DIR)/files.html $(SUBPLOT_DIR)/files.md; fi

	$(SUBPLOT) libdocgen python/lib/daemon.yaml --output $(SUBPLOT_DIR)/daemon.md
	if which pandoc>/dev/null; then pandoc --toc --standalone --self-contained --metadata "title=lib/daemon"  --output $(SUBPLOT_DIR)/daemon.html $(SUBPLOT_DIR)/daemon.md; fi

.PHONY: userguide
userguide:
	$(SUBPLOT) docgen book/user-guide.subplot --output book/user-guide.html