github.com/cilium/cilium@v1.16.2/Documentation/Makefile (about) 1 # Copyright Authors of Cilium 2 # SPDX-License-Identifier: Apache-2.0 3 4 include ../Makefile.defs 5 include ../Makefile.quiet 6 7 HELM_VALUES := helm-values.rst 8 REQUIREMENTS_NODEP := requirements-min/requirements.txt 9 REQUIREMENTS := requirements.txt 10 SPHINX_OPTS := "-j=auto" 11 12 .PHONY: default clean help builder-image cilium-build cmdref epub latex html 13 14 ##@ Targets (default: "html") 15 16 default: html 17 18 define build_image 19 $(ECHO_DOCKER) $(3) 20 # Pre-pull FROM docker image due to Buildkit sometimes failing to pull them. 21 grep -m 1 "^FROM " $(1) | tr -d '\r' | cut -d ' ' -f2 | xargs -n1 $(CONTAINER_ENGINE) pull 22 $(QUIET)tar c $(REQUIREMENTS) Dockerfile \ 23 | $(CONTAINER_ENGINE) build $(DOCKER_BUILD_FLAGS) \ 24 --build-arg READTHEDOCS_VERSION \ 25 --target $(2) --tag $(3) - 26 endef 27 28 ##@ Development Images 29 30 DOCS_BASE_IMG ?= cilium/docs-base 31 base-image: Dockerfile ## Build the docs-base image for updating the requirements.txt file. 32 $(call build_image,$<,docs-base,$(DOCS_BASE_IMG)) 33 34 DOCS_BUILDER_IMG ?= cilium/docs-builder 35 ifndef SKIP_BUILDER_IMAGE 36 builder-image: Dockerfile $(REQUIREMENTS) ## Build the docs-builder image for rendering and checking the documentation. 37 $(call build_image,$<,docs-builder,$(DOCS_BUILDER_IMG)) 38 else 39 builder-image: 40 @echo "SKIP_BUILDER_IMAGE set, assuming image is already present and up-to-date." 41 endif 42 43 # cilium must have all build artifacts present for 44 # documentation to be generated correctly. 45 cilium-build: 46 ifndef SKIP_BUILD 47 $(MAKE) builder-image 48 ../contrib/scripts/builder.sh env MAKEFLAGS="$(MAKEFLAGS)" make build 49 else 50 echo "SKIP_BUILD set, assuming all build artifacts are already present." 51 endif 52 53 READTHEDOCS_VERSION ?= latest 54 DOCKER_CTR_ROOT_DIR := /src 55 DOCKER_CTR_BASE := $(CONTAINER_ENGINE) container run --rm \ 56 --workdir $(DOCKER_CTR_ROOT_DIR)/Documentation \ 57 --env GIT_CONFIG_COUNT=1 \ 58 --env GIT_CONFIG_KEY_0=safe.directory \ 59 --env GIT_CONFIG_VALUE_0=$(DOCKER_CTR_ROOT_DIR) \ 60 --volume $(CURDIR)/..:$(DOCKER_CTR_ROOT_DIR) \ 61 --user "$(shell id -u):$(shell id -g)" 62 DOCKER_CTR := $(DOCKER_CTR_BASE) \ 63 --env READTHEDOCS_VERSION=$(READTHEDOCS_VERSION) \ 64 --env SKIP_LINT=$(SKIP_LINT) \ 65 --env INCREMENTAL=$(INCREMENTAL) 66 DOCKER_RUN := $(DOCKER_CTR) $(DOCS_BUILDER_IMG) 67 68 ##@ Auto-generated Contents Updates and Validation 69 70 .PHONY: api-flaggen 71 api-flaggen: ## Update the table of API flags restrictions. 72 @$(ECHO_GEN) api-flags 73 $(QUIET)$(GO) run $(ROOT_DIR)/tools/api-flaggen \ 74 2>/dev/null \ 75 > configuration/api-restrictions-table.rst 76 77 .PHONY: update-cmdref 78 update-cmdref: cilium-build ## Update the command reference documents (agent, bugtool, operators, etc.). 79 @$(ECHO_GEN)cmdref 80 -$(QUIET)rm -rf cmdref/cilium*.md 81 $(QUIET)$(DOCKER_RUN) ./update-cmdref.sh 82 83 .PHONY: codeowners.rst 84 codeowners.rst: 85 @$(ECHO_GEN)$@ 86 $(QUIET)$(DOCKER_RUN) ./update-codeowners.sh 87 88 .PHONY: update-codeowners 89 update-codeowners: codeowners.rst ## Update the description of the code owner teams. 90 91 .PHONY: update-crdlist 92 update-crdlist: ## Update the list of CRDs. 93 @$(ECHO_GEN)crdlist 94 make -C ../ generate-crd-docs 95 96 update-helm-values: $(HELM_VALUES) ## Update the Helm reference documentation. 97 98 HELM_DOCS_ROOT_PATH := $(DOCKER_CTR_ROOT_DIR) 99 HELM_DOCS_CHARTS_DIR := $(HELM_DOCS_ROOT_PATH)/install/kubernetes 100 HELM_DOCS_OUTPUT_DIR := $(HELM_DOCS_ROOT_PATH)/Documentation 101 HELM_DOCS := $(DOCKER_CTR) $(HELM_TOOLBOX_IMAGE) helm-docs 102 103 M2R := $(DOCKER_CTR) $(HELM_TOOLBOX_IMAGE) python3 /usr/bin/m2r2 104 105 .PHONY: update-helm-values FORCE 106 $(HELM_VALUES): TMP_FILE_1 := helm-values.tmp 107 $(HELM_VALUES): TMP_FILE_2 := helm-values.awk 108 $(HELM_VALUES): TMP_FILE_3 := helm-values.sed 109 $(HELM_VALUES): FORCE 110 $(QUIET)$(HELM_DOCS) -d -c $(HELM_DOCS_CHARTS_DIR) -t $(HELM_DOCS_OUTPUT_DIR)/$(TMP_FILE_1).tmpl > $(TMP_FILE_1) 111 $(QUIET)awk -F'|' '{print "|"$$2"|"$$5"|"$$3"|"$$4"|"}' $(TMP_FILE_1) > $(TMP_FILE_2) 112 $(QUIET)$(M2R) --overwrite $(TMP_FILE_2) 113 $(QUIET)$(SED) 's/^\( \* - \)\([[:print:]]\{1,\}\)$$/\1:spelling:ignore:`\2`/' $@ > $(TMP_FILE_3) 114 $(QUIET)printf '..\n %s\n\n%s\n' "AUTO-GENERATED. Please DO NOT edit manually." "$$(cat $(TMP_FILE_3))" > $@ 115 $(QUIET)$(RM) -- $(TMP_FILE_1) $(TMP_FILE_2) $(TMP_FILE_3) 116 117 check: builder-image api-flaggen update-cmdref update-crdlist update-helm-values update-codeowners ## Validate command and Helm references, policy examples, and others. 118 @$(ECHO_CHECK) cmdref 119 $(QUIET) ./check-cmdref.sh 120 @$(ECHO_CHECK) $(HELM_VALUES) 121 $(QUIET) ./check-helmvalues.sh 122 @$(ECHO_CHECK) examples 123 $(QUIET)$(DOCKER_RUN) ./check-examples.sh 124 @$(ECHO_CHECK) codeowners.rst 125 $(QUIET) ./check-codeowners.sh 126 @$(ECHO_CHECK) configuration/api-restrictions-table.rst 127 $(QUIET) ./check-flaggen.sh 128 @$(ECHO_CHECK) crdlist.rst 129 $(QUIET) ./check-crdlist.sh 130 131 ##@ Build 132 133 ifeq ($(V),0) 134 SPHINX_OPTS += -q 135 endif 136 137 html epub latex: builder-image ## Check documentation and render it under the specified format. 138 @$(ECHO_GEN)_build/$@ 139 $(QUIET)$(DOCKER_RUN) ./check-build.sh $(@) $(SPHINX_OPTS) 140 141 html-netlify: 142 @$(ECHO_GEN)_build/$@ 143 $(QUIET) SKIP_LINT=1 ./check-build.sh html $(SPHINX_OPTS) 144 145 DOCS_PORT = 9081 146 147 live-preview: builder-image ## Build and serve the documentation locally. 148 @echo "$$(tput setaf 2)Running at http://localhost:$(DOCS_PORT)$$(tput sgr0)" 149 $(QUIET)$(DOCKER_CTR) \ 150 --publish $(DOCS_PORT):$(DOCS_PORT) \ 151 $(DOCS_BUILDER_IMG) \ 152 sphinx-autobuild --open-browser --host 0.0.0.0 --port $(DOCS_PORT) $(SPHINX_OPTS) --ignore *.swp -Q . _preview 153 154 update-redirects: builder-image ## Build and serve the documentation locally. 155 @echo "$$(tput setaf 2)Writing redirects$$(tput sgr0)" 156 $(QUIET)$(DOCKER_CTR) \ 157 $(DOCS_BUILDER_IMG) \ 158 sphinx-build -M rediraffewritediff . _preview 159 160 ##@ Development 161 162 update-requirements: base-image $(REQUIREMENTS_NODEP) ## Regenerate the requirements.txt file from requirements-min/requirements.txt. 163 @echo '## Auto-generated from $(REQUIREMENTS_NODEP) with "make update-requirements"' > $(REQUIREMENTS) 164 $(QUIET)$(DOCKER_CTR_BASE) $(DOCS_BASE_IMG) \ 165 bash -c "export HOME=/tmp && pip install --no-warn-script-location -r $(REQUIREMENTS_NODEP) && pip freeze -r $(REQUIREMENTS_NODEP) >> $(REQUIREMENTS)" 166 167 clean: ## Clean up all artefacts from documentation. 168 -$(QUIET)rm -rf _build _exts/__pycache__ _preview Pipfile Pipfile.lock 169 170 help: ## Display help for the Makefile. 171 $(call print_help_from_makefile)