book.opensvc.com/Makefile at main · opensvc/book.opensvc.com · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
-include Makefile.inc

SHELL := /bin/bash

# The keyword reference is generated by the agent of a release and published
# with it, as keywords-<tag>.tar.gz. The book takes it from there rather than
# running an om binary of its own: a binary built without "make version" names
# a version it is not, and a book generated from it documents a release that
# never existed.
#
#	make kw KEYWORDS_VERSION=v3.1.0        # from the release
#	make kw KEYWORDS_TARBALL=/path/to.tgz  # from a file, to try one out
KEYWORDS_VERSION ?=
KEYWORDS_TARBALL ?=
KEYWORDS_URL ?= https://github.com/opensvc/om3/releases/download/$(KEYWORDS_VERSION)/keywords-$(KEYWORDS_VERSION).tar.gz

KWDIR = src/agent.reference.keywords
KINDS = node cluster svc vol sec cfg usr

.ONESHELL: kw summary changes
.SILENT: kw summary changes

all: summary build

# kw lays the keyword reference of a release into the tracked tree.
#
# It is run when a release is cut, and its result committed: the book then
# builds anywhere, with no agent and no network, and a keyword change arrives
# in a pull request as a diff a reviewer can read.
kw:
	set -e
	tmp=$$(mktemp -d)
	trap "rm -rf $$tmp" EXIT
	if [ -n "$(KEYWORDS_TARBALL)" ]; then
		tar xzf "$(KEYWORDS_TARBALL)" -C $$tmp
	elif [ -n "$(KEYWORDS_VERSION)" ]; then
		curl -sSfL "$(KEYWORDS_URL)" | tar xz -C $$tmp
	else
		echo "KEYWORDS_VERSION=<release tag> or KEYWORDS_TARBALL=<file> is required" >&2
		exit 1
	fi
	src=$$(echo $$tmp/keywords-*)
	# The version the reference documents is the one the agent that generated
	# it reported, and is read from the artifact rather than guessed here.
	version=$$(cat $$src/version)
	# The timeline outlives the reference: the pages are those of one
	# release and are replaced by the next, the timeline is every release
	# there has been.
	[ -f $(KWDIR)/history.json ] && cp $(KWDIR)/history.json $$tmp/history.json || true
	rm -rf $(KWDIR)
	mkdir -p $(KWDIR)
	[ -f $$tmp/history.json ] && cp $$tmp/history.json $(KWDIR)/history.json || true
	summary="SUMMARY.md.in"
	echo -e "# Agent Keywords Reference ($$version)\n" >$(KWDIR)/$${summary}
	head=$$(pwd)
	for kind in $(KINDS); do
		echo "- [$${kind}](agent.reference.keywords/$${kind}/SUMMARY.md)" >>$(KWDIR)/$${summary}
		mkdir -p $(KWDIR)/$${kind}
		printf "# $${kind}\n\n" >$(KWDIR)/$${kind}/SUMMARY.md
		cd $(KWDIR)/$${kind}
		csplit -q -z $$src/$${kind}.md "/^# /" {*}
		for f in $$(echo xx*); do
			title=$$(head -n1 $$f|cut -d'`' -f2)
			mv $${f} $${title}.md
			echo "  - [$${title}](agent.reference.keywords/$${kind}/$${title}.md)" >>../$${summary}
			echo "- [$${title}]($${title}.md)" >>../$${kind}/SUMMARY.md
		done
		cd $$head
	done
	# The index is the corpus of this release, and the timeline is what it
	# is compared with: the book documents the newest release, and the
	# timeline says when a keyword appeared, when it went away, and what
	# moved in between. A removed keyword is recorded nowhere else, a
	# release having nothing to say about what it does not carry.
	tools/kwindex.py --version "$$version" --out $(KWDIR)/index.json $$src/*.json
	tools/kwhistory.py update --history $(KWDIR)/history.json --index $(KWDIR)/index.json
	tools/kwhistory.py render --history $(KWDIR)/history.json --dir $(KWDIR)
	summary="$(KWDIR)/SUMMARY.md.in"
	sed -i "2a - [Keyword changes](agent.reference.keywords/changes.md)\n- [Removed keywords](agent.reference.keywords/removed.md)" $${summary}

summary:
	cat src/preamble/SUMMARY.md.in src/agent/SUMMARY.md.in src/howtos/SUMMARY.md.in src/appendix/SUMMARY.md.in src/agent.reference.keywords/SUMMARY.md.in > src/SUMMARY.md

build:
	mdbook build