Merge pull request #7033 from oscr/fix-docs-makefile

✨ Update docs/Makefile

Author: k8s-ci-robot

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)
@@ -24,13 +25,26 @@ ifeq ($(SELINUX_ENABLED),1)
   DOCKER_VOL_OPTS?=:z
 endif
 
+##@ PlantUML diagrams
+
 .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  diagrams-book diagrams-proposals ## Make all diagrams
+
+.PHONY: diagrams-book
+diagrams-book: plantuml-builder ## Make all book diagrams
+	-docker run -u $(UID):$(GID) -v $(abspath .):/docs$(DOCKER_VOL_OPTS) plantuml-builder /docs/book/**/*.md
+	-docker run -u $(UID):$(GID) -v $(abspath .):/docs$(DOCKER_VOL_OPTS) plantuml-builder /docs/book/**/*.plantuml
+
+.PHONY: diagrams-proposals
+diagrams-proposals: plantuml-builder ## Make all proposals diagrams
+	-docker run -u $(UID):$(GID) -v $(abspath .):/docs$(DOCKER_VOL_OPTS) plantuml-builder /docs/proposals/**/*.md
+	-docker run -u $(UID):$(GID) -v $(abspath .):/docs$(DOCKER_VOL_OPTS) plantuml-builder /docs/proposals/**/*.plantuml
+
+.PHONY: plantuml-builder
+plantuml-builder: Dockerfile  ## Make diagram build container
+	docker build -f Dockerfile -t "plantuml-builder" .
+
+##@ general
+
+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)

docs/proposals/images/capi-provider-operator/fig1.png

@@ -16,7 +16,7 @@ end box
 
 User -> "API Server" : Create Cluster object with\n""Cluster.Spec.Managed.Class""
 "API Server" --> "Cluster Controller": New Cluster
-opt Required only if Cluster.Spec.Managed.Class is set
+opt #white Required only if Cluster.Spec.Managed.Class is set
 "Cluster Controller" --> "API Server": Creates the infrastructure cluster
 "Cluster Controller" -> "Cluster Controller": Checks for\nCluster.Spec.ControlPlaneRef
 opt Required only if Cluster.Spec.ControlPlaneRef is not set

docs/proposals/images/capi-provider-operator/fig2.png

@@ -16,7 +16,7 @@ end box
 
 User -> "API Server" : Update Cluster object with\n""Cluster.Spec.Class""
 "API Server" --> "Cluster Controller": Existing Cluster
-opt Required only if Cluster.Spec.Class is set
+opt #white Required only if Cluster.Spec.Class is set
   "Cluster Controller" -> "Cluster Controller": Fetches the InfrastructureCluster object\nset in Cluster.spec.infrastructureRef
   opt Update the InfrastructureCluster
     "Cluster Controller" -> "Cluster Controller": Updates InfrastructureCluster fields

docs/proposals/images/cluster-class/create.plantuml

@@ -21,24 +21,24 @@ end box
 User -> "API Server" : Create Cluster Infrastructure
 "API Server" -->> "Infrastructure Controller": New Provider Infrastructure
 
-opt IF Infrastructure has no owner ref
+opt #white IF Infrastructure has no owner ref
 "Infrastructure Controller"->"Infrastructure Controller": Do Nothing
 end
 
 User -> "API Server": Create Cluster
 "API Server" -->> "Cluster Controller": New Cluster
 "Cluster Controller" -> "API Server": Get Infrastructure
-opt Required Only if Infrastructure not seen before
+opt #white Required Only if Infrastructure not seen before
 "Cluster Controller" -> "Cluster Controller": Add Watcher for Cluster.InfrastructureRef.Kind objects
 end
 
-opt Required Only if Infrastructure has no owner
+opt #white Required Only if Infrastructure has no owner
 "Cluster Controller" -> "Cluster Controller": Set Infrastructure's owner to Cluster
 "Cluster Controller" -> "API Server": Update Infrastructure
 end
 
 "API Server" -->> "Infrastructure Controller": Infrastructure update
-opt Required only if Infrastructure has owner ref
+opt #white Required only if Infrastructure has owner ref
 "Infrastructure Controller" -> "API Server": Get Cluster
 "Infrastructure Controller" -> "Infrastructure Controller": Provision infrastructure
 "Infrastructure Controller" -> "Infrastructure Controller": Set Infrastructure.Status.APIEndpoint
@@ -47,7 +47,7 @@ opt Required only if Infrastructure has owner ref
 end
 
 "API Server" -->> "Cluster Controller": Infrastructure Update
-opt Only required if Infrastructure.Status.Ready is true
+opt #white Only required if Infrastructure.Status.Ready is true
 "Cluster Controller" -> "API Server": Get Cluster
 "Cluster Controller" -> "Cluster Controller": Set Cluster.Status.APIEndpoint = Infrastructure.Status.APIEndpoint
 "Cluster Controller" -> "Cluster Controller": Set Cluster.Status.InfrastructureReady true