diff --git a/docs/docs.mk b/docs/docs.mk index a08830d907c..c0aae10ba50 100644 --- a/docs/docs.mk +++ b/docs/docs.mk @@ -65,6 +65,11 @@ ifeq ($(origin HUGO_REFLINKSERRORLEVEL), undefined) export HUGO_REFLINKSERRORLEVEL := WARNING endif +# Whether to pull the latest container image before running the container. +ifeq ($(origin PULL), undefined) +export PULL := true +endif + .PHONY: docs-rm docs-rm: ## Remove the docs container. $(PODMAN) rm -f $(DOCS_CONTAINER) @@ -81,13 +86,12 @@ make-docs: fi .PHONY: docs -docs: ## Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. See also `docs-no-pull`. +docs: ## Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. To not pull the image, set `PULL=false`. +ifeq ($(PULL), true) docs: docs-pull make-docs - $(CURDIR)/make-docs $(PROJECTS) - -.PHONY: docs-no-pull -docs-no-pull: ## Serve documentation locally without pulling the `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. -docs-no-pull: make-docs +else +docs: make-docs +endif $(CURDIR)/make-docs $(PROJECTS) .PHONY: docs-debug @@ -96,13 +100,19 @@ docs-debug: make-docs WEBSITE_EXEC='hugo server --bind 0.0.0.0 --port 3002 --debug' $(CURDIR)/make-docs $(PROJECTS) .PHONY: doc-validator -doc-validator: ## Run doc-validator on the entire docs folder. +doc-validator: ## Run doc-validator on the entire docs folder which includes pulling the latest `DOC_VALIDATOR_IMAGE` (default: `grafana/doc-validator:latest`) container image. To not pull the image, set `PULL=false`. doc-validator: make-docs +ifeq ($(PULL), true) + $(PODMAN) pull -q $(DOC_VALIDATOR_IMAGE) +endif DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(CURDIR)/make-docs $(PROJECTS) .PHONY: vale -vale: ## Run vale on the entire docs folder. +vale: ## Run vale on the entire docs folder which includes pulling the latest `VALE_IMAGE` (default: `grafana/vale:latest`) container image. To not pull the image, set `PULL=false`. vale: make-docs +ifeq ($(PULL), true) + $(PODMAN) pull -q $(VALE_IMAGE) +endif DOCS_IMAGE=$(VALE_IMAGE) $(CURDIR)/make-docs $(PROJECTS) .PHONY: update diff --git a/docs/make-docs b/docs/make-docs index 43efdb5faad..0a1730e6c6f 100755 --- a/docs/make-docs +++ b/docs/make-docs @@ -6,6 +6,32 @@ # [Semantic versioning](https://semver.org/) is used to help the reader identify the significance of changes. # Changes are relevant to this script and the support docs.mk GNU Make interface. # +# ## 7.0.0 (2024-05-03) +# +# ### Changed +# +# - Pull images for all recipes that use containers by default. +# +# Use the `PULL=false` variable to disable this behavior. +# +# ### Removed +# +# - The `docs-no-pull` target as it's redundant with the new `PULL=false` variable. +# +# ## 6.1.0 (2024-04-22) +# +# ### Changed +# +# - Mount volumes with SELinux labels. +# +# https://docs.docker.com/storage/bind-mounts/#configure-the-selinux-label +# +# ### Added +# +# - Pseudo project for including only website resources and no website content. +# +# Facilitates testing shortcodes and layout changes with a small documentation set instead of Grafana Cloud or the entire website. +# # ## 6.0.1 (2024-02-28) # # ### Added @@ -300,6 +326,7 @@ SOURCES_helm_charts_tempo_distributed='tempo' SOURCES_opentelemetry='opentelemetry-docs' SOURCES_plugins_grafana_datadog_datasource='datadog-datasource' SOURCES_plugins_grafana_oracle_datasource='oracle-datasource' +SOURCES_resources='website' VERSIONS_as_code='UNVERSIONED' VERSIONS_grafana_cloud='UNVERSIONED' @@ -311,6 +338,7 @@ VERSIONS_grafana_cloud_frontend_observability_faro_web_sdk='UNVERSIONED' VERSIONS_opentelemetry='UNVERSIONED' VERSIONS_plugins_grafana_datadog_datasource='latest' VERSIONS_plugins_grafana_oracle_datasource='latest' +VERSIONS_resources='UNVERSIONED' VERSIONS_technical_documentation='UNVERSIONED' VERSIONS_website='UNVERSIONED' VERSIONS_writers_toolkit='UNVERSIONED' @@ -321,6 +349,7 @@ PATHS_helm_charts_tempo_distributed='docs/sources/helm-charts/tempo-distributed' PATHS_mimir='docs/sources/mimir' PATHS_plugins_grafana_datadog_datasource='docs/sources' PATHS_plugins_grafana_oracle_datasource='docs/sources' +PATHS_resources='content' PATHS_tempo='docs/sources/tempo' PATHS_website='content' @@ -584,6 +613,11 @@ POSIX_HERESTRING proj_to_url_src_dst_ver "$(new_proj helm-charts/mimir-distributed "${_version}")" proj_to_url_src_dst_ver "$(new_proj enterprise-metrics "${_version}")" ;; + resources) + _repo="$(repo_path website)" + echo "arbitrary^${_repo}/config^/hugo/config" "arbitrary^${_repo}/layouts^/hugo/layouts" "arbitrary^${_repo}/scripts^/hugo/scripts" + unset _repo + ;; traces) proj_to_url_src_dst_ver "$(new_proj tempo "${_version}")" proj_to_url_src_dst_ver "$(new_proj enterprise-traces "${_version}")" @@ -617,7 +651,7 @@ $x POSIX_HERESTRING if [ -n "${url}" ]; then - if [ "${_url}" != "arbitrary" ]; then + if [ "${url}" != arbitrary ]; then printf '\r %s\r\n' "${url}" fi fi @@ -670,9 +704,9 @@ POSIX_HERESTRING fi _repo="$(repo_path website)" - volumes="--volume=${_repo}/config:/hugo/config" - volumes="${volumes} --volume=${_repo}/layouts:/hugo/layouts" - volumes="${volumes} --volume=${_repo}/scripts:/hugo/scripts" + volumes="--volume=${_repo}/config:/hugo/config:z" + volumes="${volumes} --volume=${_repo}/layouts:/hugo/layouts:z" + volumes="${volumes} --volume=${_repo}/scripts:/hugo/scripts:z" fi unset _project _repo done @@ -682,7 +716,7 @@ for x in ${url_src_dst_vers}; do $x POSIX_HERESTRING - if [ "${_url}" != "arbitrary" ]; then + if [ "${_url}" != arbitrary ]; then if [ ! -f "${_src}/_index.md" ]; then errr "Index file '${_src}/_index.md' does not exist." note "Is '${_src}' the correct source directory?" @@ -693,9 +727,9 @@ POSIX_HERESTRING debg "Mounting '${_src}' at container path '${_dst}'" if [ -z "${volumes}" ]; then - volumes="--volume=${_src}:${_dst}" + volumes="--volume=${_src}:${_dst}:z" else - volumes="${volumes} --volume=${_src}:${_dst}" + volumes="${volumes} --volume=${_src}:${_dst}:z" fi if [ -n "${_ver}" ] && [ "${_ver}" != 'UNVERSIONED' ]; then @@ -789,7 +823,7 @@ fi ${WEBSITE_EXEC} EOF chmod +x "${tempfile}" - volumes="${volumes} --volume=${tempfile}:/entrypoint" + volumes="${volumes} --volume=${tempfile}:/entrypoint:z" readonly volumes IFS='' read -r cmd <