Update docs/Makefile

* Add help target
* Add diagram build container target
* Update diagram build target to use local image
* Update Dockerfile usage instructions

docs/Dockerfile

@@ -14,21 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Recommended usage:
-#
-# - Run an ephemeral container
-# - Mount the current working directory into the container.
-# - Run the entrypoint as the user invoking docker run. Otherwise the output
-#   files will be owned by root, the default user.
-#
-# - Example:
-# docker run \
-# 	--rm \
-# 	--volume ${PWD}:/figures \
-# 	--user $(id --user):$(id --group) \
-# 	${IMAGE_TAG} \
-# 	-v /figures/*.plantuml
-
+# To generate diagrams run 'make diagrams' in the docs/ folder.
 FROM maven:3-jdk-8
 
 RUN apt-get update && apt-get install -y --no-install-recommends graphviz=2.42.2-5 fonts-symbola=2.60-1.1 fonts-wqy-zenhei=0.9.45-8 && rm -rf /var/lib/apt/lists/*

docs/Makefile

@@ -12,10 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-ROOT_DIR:=$(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
+SHELL:=/usr/bin/env bash
 
-SOURCES := $(shell find ${ROOT_DIR} -name \*.plantuml)
-DIAGRAMS := $(SOURCES:%.plantuml=%.png)
+.DEFAULT_GOAL:=help
+
+DIAGRAM_SRCS := $(call rwildcard,.,*.md,*.plantuml)
 
 # Hosts running SELinux need :z added to volume mounts
 SELINUX_ENABLED := $(shell cat /sys/fs/selinux/enforce 2> /dev/null || echo 0)
@@ -25,12 +26,13 @@ ifeq ($(SELINUX_ENABLED),1)
 endif
 
 .PHONY: diagrams
-diagrams: $(DIAGRAMS)
-
-%.png: %.plantuml
-	docker run \
-		--rm \
-		--volume ${ROOT_DIR}:/workdir$(DOCKER_VOL_OPTS) \
-		--user $(shell id -u):$(shell id -g) \
-		k8s.gcr.io/cluster-api/plantuml:1.2019.6 \
-		-v /workdir/$(shell echo '$^' | sed -e 's,.*docs/,,g' )
+diagrams: plantuml-builder  ## Make PlantUML diagrams
+	-docker run -u $(UID):$(GID) -v $(abspath .):/docs$(DOCKER_VOL_OPTS) plantuml-builder /docs/**/*.md
+	-docker run -u $(UID):$(GID) -v $(abspath .):/docs$(DOCKER_VOL_OPTS) plantuml-builder /docs/**/*.plantuml
+
+.PHONY: plantuml-builder
+plantuml-builder: Dockerfile  ## Make diagram build container
+	docker build -f Dockerfile -t "plantuml-builder" .
+
+help:  ## Display this help
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z0-9_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)