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)