Update make docs procedure (#4523)
Co-authored-by: grafanabot <bot@grafana.com> Co-authored-by: Joey Orlando <joey.orlando@grafana.com>
This commit is contained in:
github-actions[bot]
GitHub
parent
56683d2aa0
commit
bc1544cc01
2 changed files with 123 additions and 37 deletions
26
docs/docs.mk
26
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
|
||||
|
|
|
|||
134
docs/make-docs
134
docs/make-docs
|
|
@ -6,6 +6,43 @@
|
|||
# [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.
|
||||
#
|
||||
# ## 8.0.0 (2024-05-28)
|
||||
#
|
||||
# ### Changed
|
||||
#
|
||||
# - Add environment variable `OUTPUT_FORMAT` to control the output of commands.
|
||||
#
|
||||
# The default value is `human` and means the output format is human readable.
|
||||
# The value `json` is also supported and outputs JSON.
|
||||
#
|
||||
# Note that the `json` format isn't supported by `make docs`, only `make doc-validator` and `make vale`.
|
||||
#
|
||||
# ## 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
|
||||
|
|
@ -229,6 +266,8 @@ readonly HUGO_REFLINKSERRORLEVEL="${HUGO_REFLINKSERRORLEVEL:-WARNING}"
|
|||
readonly VALE_MINALERTLEVEL="${VALE_MINALERTLEVEL:-error}"
|
||||
readonly WEBSITE_EXEC="${WEBSITE_EXEC:-make server-docs}"
|
||||
|
||||
readonly OUTPUT_FORMAT="${OUTPUT_FORMAT:-human}"
|
||||
|
||||
PODMAN="$(if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)"
|
||||
|
||||
if ! command -v curl >/dev/null 2>&1; then
|
||||
|
|
@ -300,6 +339,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 +351,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 +362,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 +626,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 +664,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 +717,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 +729,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 +740,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
|
||||
|
|
@ -714,45 +761,74 @@ POSIX_HERESTRING
|
|||
|
||||
case "${image}" in
|
||||
'grafana/doc-validator')
|
||||
if ! command -v jq >/dev/null 2>&1; then
|
||||
errr '`jq` must be installed for the `doc-validator` target to work.'
|
||||
note 'To install `jq`, refer to https://jqlang.github.io/jq/download/,'
|
||||
|
||||
exit 1
|
||||
fi
|
||||
|
||||
proj="$(new_proj "$1")"
|
||||
printf '\r\n'
|
||||
"${PODMAN}" run \
|
||||
|
||||
IFS='' read -r cmd <<EOF
|
||||
${PODMAN} run \
|
||||
--init \
|
||||
--interactive \
|
||||
--platform linux/amd64 \
|
||||
--rm \
|
||||
--tty \
|
||||
${volumes} \
|
||||
"${DOCS_IMAGE}" \
|
||||
"--include=${DOC_VALIDATOR_INCLUDE}" \
|
||||
"--skip-checks=${DOC_VALIDATOR_SKIP_CHECKS}" \
|
||||
"/hugo/content$(proj_canonical "${proj}")" \
|
||||
"$(proj_canonical "${proj}")" \
|
||||
| sed "s#$(proj_dst "${proj}")#sources#" \
|
||||
| jq -r '"ERROR: \(.location.path):\(.location.range.start.line // 1):\(.location.range.start.column // 1): \(.message)" + if .suggestions[0].text then "\nSuggestion: \(.suggestions[0].text)" else "" end'
|
||||
${DOCS_IMAGE} \
|
||||
--include=${DOC_VALIDATOR_INCLUDE} \
|
||||
--skip-checks=${DOC_VALIDATOR_SKIP_CHECKS} \
|
||||
/hugo/content$(proj_canonical "${proj}") \
|
||||
"$(proj_canonical "${proj}") \
|
||||
| sed "s#$(proj_dst "${proj}")#sources#"
|
||||
EOF
|
||||
|
||||
case "${OUTPUT_FORMAT}" in
|
||||
human)
|
||||
if ! command -v jq >/dev/null 2>&1; then
|
||||
errr '`jq` must be installed for the `doc-validator` target to work.'
|
||||
note 'To install `jq`, refer to https://jqlang.github.io/jq/download/,'
|
||||
|
||||
exit 1
|
||||
fi
|
||||
|
||||
${cmd} \
|
||||
| jq -r '"ERROR: \(.location.path):\(.location.range.start.line // 1):\(.location.range.start.column // 1): \(.message)" + if .suggestions[0].text then "\nSuggestion: \(.suggestions[0].text)" else "" end'
|
||||
;;
|
||||
json)
|
||||
${cmd}
|
||||
;;
|
||||
*) # default
|
||||
errr "Invalid output format '${OUTPUT_FORMAT}'"
|
||||
esac
|
||||
;;
|
||||
'grafana/vale')
|
||||
proj="$(new_proj "$1")"
|
||||
printf '\r\n'
|
||||
"${PODMAN}" run \
|
||||
IFS='' read -r cmd <<EOF
|
||||
${PODMAN} run \
|
||||
--init \
|
||||
--interactive \
|
||||
--rm \
|
||||
--workdir /etc/vale \
|
||||
--tty \
|
||||
${volumes} \
|
||||
"${DOCS_IMAGE}" \
|
||||
"--minAlertLevel=${VALE_MINALERTLEVEL}" \
|
||||
'--glob=*.md' \
|
||||
--output=/etc/vale/rdjsonl.tmpl \
|
||||
/hugo/content/docs | sed "s#$(proj_dst "${proj}")#sources#"
|
||||
${DOCS_IMAGE} \
|
||||
--minAlertLevel=${VALE_MINALERTLEVEL} \
|
||||
--glob=*.md \
|
||||
/hugo/content/docs
|
||||
EOF
|
||||
|
||||
case "${OUTPUT_FORMAT}" in
|
||||
human)
|
||||
${cmd} --output=line \
|
||||
| sed "s#$(proj_dst "${proj}")#sources#"
|
||||
;;
|
||||
json)
|
||||
${cmd} --output=/etc/vale/rdjsonl.tmpl \
|
||||
| sed "s#$(proj_dst "${proj}")#sources#"
|
||||
;;
|
||||
*)
|
||||
errr "Invalid output format '${OUTPUT_FORMAT}'"
|
||||
esac
|
||||
|
||||
;;
|
||||
*)
|
||||
tempfile="$(mktemp -t make-docs.XXX)"
|
||||
|
|
@ -789,7 +865,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 <<EOF
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue