apitech
/
grafana
mirror of https://github.com/grafana/grafana
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update `make docs` procedure (#77536)

Browse Source 
* Update `make docs` procedure

* Update `make docs` procedure

---------

Co-authored-by: grafanabot <bot@grafana.com>
pull/77780/head
github-actions[bot] 2 years ago committed by GitHub
parent 4a5b8643ae
commit f9fffd3ff1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 213 additions and 95 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 5
      docs/docs.mk
  2. 281
      docs/make-docs

5
docs/docs.mk
Unescape View File

@ -34,11 +34,6 @@ endif
# First project is considered the primary one used for doc-validator. # First project is considered the primary one used for doc-validator.
PRIMARY_PROJECT := $(subst /,-,$(firstword $(subst :, ,$(firstword $(PROJECTS))))) PRIMARY_PROJECT := $(subst /,-,$(firstword $(subst :, ,$(firstword $(PROJECTS)))))
# Name for the container.
ifeq ($(origin DOCS_CONTAINER), undefined)
export DOCS_CONTAINER := $(PRIMARY_PROJECT)-docs
endif
# Host port to publish container port to. # Host port to publish container port to.
ifeq ($(origin DOCS_HOST_PORT), undefined) ifeq ($(origin DOCS_HOST_PORT), undefined)
export DOCS_HOST_PORT := 3002 export DOCS_HOST_PORT := 3002

281
docs/make-docs
Unescape View File

@ -5,107 +5,146 @@
# Updates should conform to the guidelines in https://keepachangelog.com/en/1.1.0/. # Updates should conform to the guidelines in https://keepachangelog.com/en/1.1.0/.
# [Semantic versioning](https://semver.org/) is used to help the reader identify the significance of changes. # [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. # Changes are relevant to this script and the support docs.mk GNU Make interface.
#
# ## 5.1.1 (2023-10-30)
#
# ### Added
#
# - Support for Datadog and Oracle data source plugins repositories.
#
# ## 5.1.0 (2023-10-20)
#
# ### Added
#
# - Support for the plugins monorepo.
#
# ## 5.0.0 (2023-10-18)
#
# ### Added
#
# - Improved support for website repository.
#
# Mount more content and provide some feedback to users that the build can take time.
#
# - Ability to enter the `grafana/docs-base` container with a shell using the `ENTER` environment variable.
#
# ### Fixed
#
# - Correct key combination for interrupting the process.
#
# Keyboards use capital letters so this more accurately reflects the exact key combination users are expected to press.
#
# ### Removed
#
# - Imperfect implementation of container name.
#
# Facilitates running `make vale` and `make docs` at once.
# Container names are convenient for recognition in `docker ps` but the current implementation has more downsides than upsides.
#
# - Forced platform specification now that multiple architecture images exist.
#
# Significantly speeds up build times on larger repositories.
#
# ## 4.2.2 (2023-10-05) # ## 4.2.2 (2023-10-05)
# - Added support for Jira data source and MongoDB data source plugins repositories. # - Added support for Jira data source and MongoDB data source plugins repositories.
#
# ## 4.2.1 (2023-09-13) # ## 4.2.1 (2023-09-13)
# ## Fixed # ## Fixed
#
# - Improved consistency of the webserver request loop by polling the Hugo port rather than the proxy port. # - Improved consistency of the webserver request loop by polling the Hugo port rather than the proxy port.
#
# ## 4.2.0 (2023-09-01) # ## 4.2.0 (2023-09-01)
#
# ### Added # ### Added
#
# - Retry the initial webserver request up to ten times to allow for the process to start. # - Retry the initial webserver request up to ten times to allow for the process to start.
# If it is still failing after ten seconds, an error message is logged. # If it is still failing after ten seconds, an error message is logged.
#
# ## 4.1.1 (2023-07-20) # ## 4.1.1 (2023-07-20)
#
# ### Fixed # ### Fixed
#
# - Replaced use of `realpath` with POSIX compatible alternative to determine default value for REPOS_PATH. # - Replaced use of `realpath` with POSIX compatible alternative to determine default value for REPOS_PATH.
#
# ## 4.1.0 (2023-06-16) # ## 4.1.0 (2023-06-16)
#
# ### Added # ### Added
#
# - Mounts of `layouts` and `config` directories for the `website` project. # - Mounts of `layouts` and `config` directories for the `website` project.
# Ensures that local changes to mounts or shortcodes are reflected in the development server. # Ensures that local changes to mounts or shortcodes are reflected in the development server.
#
# ### Fixed # ### Fixed
#
# - Version inference for versioned docs pages. # - Version inference for versioned docs pages.
# Pages in versioned projects now have the `versioned: true` front matter set to ensure that "version" in $.Page.Scratch is set on builds. # Pages in versioned projects now have the `versioned: true` front matter set to ensure that "version" in $.Page.Scratch is set on builds.
#
# ## 4.0.0 (2023-06-06) # ## 4.0.0 (2023-06-06)
#
# ### Removed # ### Removed
#
# - `doc-validator/%` target. # - `doc-validator/%` target.
# The behavior of the target was not as described. # The behavior of the target was not as described.
# Instead, to limit `doc-validator` to only specific files, refer to https://grafana.com/docs/writers-toolkit/writing-guide/tooling-and-workflows/validate-technical-documentation/#run-on-specific-files. # Instead, to limit `doc-validator` to only specific files, refer to https://grafana.com/docs/writers-toolkit/writing-guide/tooling-and-workflows/validate-technical-documentation/#run-on-specific-files.
#
# ## 3.0.0 (2023-05-18) # ## 3.0.0 (2023-05-18)
#
# ### Fixed # ### Fixed
#
# - Compatibility with the updated Make targets in the `website` repository. # - Compatibility with the updated Make targets in the `website` repository.
# `docs` now runs this script itself, `server-docs` builds the site with the `docs` Hugo environment. # `docs` now runs this script itself, `server-docs` builds the site with the `docs` Hugo environment.
#
# ## 2.0.0 (2023-05-18) # ## 2.0.0 (2023-05-18)
#
# ### Added # ### Added
#
# - Support for the grafana-cloud/frontend-observability/faro-web-sdk project. # - Support for the grafana-cloud/frontend-observability/faro-web-sdk project.
# - Use of `doc-validator` v2.0.x which includes breaking changes to command line options. # - Use of `doc-validator` v2.0.x which includes breaking changes to command line options.
#
# ### Fixed # ### Fixed
#
# - Source grafana-cloud project from website repository. # - Source grafana-cloud project from website repository.
#
# ### Added # ### Added
#
# - Support for running the Vale linter with `make vale`. # - Support for running the Vale linter with `make vale`.
#
# ## 1.2.1 (2023-05-05) # ## 1.2.1 (2023-05-05)
#
# ### Fixed # ### Fixed
#
# - Use `latest` tag of `grafana/vale` image by default instead of hardcoded older version. # - Use `latest` tag of `grafana/vale` image by default instead of hardcoded older version.
# - Fix mounting multiple projects broken by the changes in 1.0.1 # - Fix mounting multiple projects broken by the changes in 1.0.1
#
# ## 1.2.0 (2023-05-05) # ## 1.2.0 (2023-05-05)
#
# ### Added # ### Added
#
# - Support for running the Vale linter with `make vale`. # - Support for running the Vale linter with `make vale`.
#
# ### Fixed # ### Fixed
#
# ## 1.1.0 (2023-05-05) # ## 1.1.0 (2023-05-05)
#
# ### Added # ### Added
#
# - Rewrite error output so it can be followed by text editors. # - Rewrite error output so it can be followed by text editors.
#
# ### Fixed # ### Fixed
#
# - Fix `docs-debug` container process port. # - Fix `docs-debug` container process port.
#
# ## 1.0.1 (2023-05-04) # ## 1.0.1 (2023-05-04)
#
# ### Fixed # ### Fixed
#
# - Ensure complete section hierarchy so that all projects have a visible menu. # - Ensure complete section hierarchy so that all projects have a visible menu.
#
# ## 1.0.0 (2023-05-04) # ## 1.0.0 (2023-05-04)
#
# ### Added # ### Added
#
# - Build multiple projects simultaneously if all projects are checked out locally. # - Build multiple projects simultaneously if all projects are checked out locally.
# - Run [`doc-validator`](https://github.com/grafana/technical-documentation/tree/main/tools/cmd/doc-validator) over projects. # - Run [`doc-validator`](https://github.com/grafana/technical-documentation/tree/main/tools/cmd/doc-validator) over projects.
# - Redirect project root to mounted version. # - Redirect project root to mounted version.
@ -135,7 +174,6 @@
set -ef set -ef
readonly DOCS_CONTAINER="${DOCS_CONTAINER:-make-docs}"
readonly DOCS_HOST_PORT="${DOCS_HOST_PORT:-3002}" readonly DOCS_HOST_PORT="${DOCS_HOST_PORT:-3002}"
readonly DOCS_IMAGE="${DOCS_IMAGE:-grafana/docs-base:latest}" readonly DOCS_IMAGE="${DOCS_IMAGE:-grafana/docs-base:latest}"
@ -217,8 +255,10 @@ SOURCES_grafana_cloud_frontend_observability_faro_web_sdk='faro-web-sdk'
SOURCES_helm_charts_mimir_distributed='mimir' SOURCES_helm_charts_mimir_distributed='mimir'
SOURCES_helm_charts_tempo_distributed='tempo' SOURCES_helm_charts_tempo_distributed='tempo'
SOURCES_opentelemetry='opentelemetry-docs' SOURCES_opentelemetry='opentelemetry-docs'
SOURCES_plugins_grafana_datadog_datasource='datadog-datasource'
SOURCES_plugins_grafana_jira_datasource='jira-datasource' SOURCES_plugins_grafana_jira_datasource='jira-datasource'
SOURCES_plugins_grafana_mongodb_datasource='mongodb-datasource' SOURCES_plugins_grafana_mongodb_datasource='mongodb-datasource'
SOURCES_plugins_grafana_oracle_datasource='oracle-datasource'
SOURCES_plugins_grafana_splunk_datasource='splunk-datasource' SOURCES_plugins_grafana_splunk_datasource='splunk-datasource'
VERSIONS_as_code='UNVERSIONED' VERSIONS_as_code='UNVERSIONED'
@ -229,6 +269,11 @@ VERSIONS_grafana_cloud_k6='UNVERSIONED'
VERSIONS_grafana_cloud_data_configuration_integrations='UNVERSIONED' VERSIONS_grafana_cloud_data_configuration_integrations='UNVERSIONED'
VERSIONS_grafana_cloud_frontend_observability_faro_web_sdk='UNVERSIONED' VERSIONS_grafana_cloud_frontend_observability_faro_web_sdk='UNVERSIONED'
VERSIONS_opentelemetry='UNVERSIONED' VERSIONS_opentelemetry='UNVERSIONED'
VERSIONS_plugins_grafana_datadog_datasource='latest'
VERSIONS_plugins_grafana_jira_datasource='latest'
VERSIONS_plugins_grafana_mongodb_datasource='latest'
VERSIONS_plugins_grafana_oracle_datasource='latest'
VERSIONS_plugins_grafana_splunk_datasource='latest'
VERSIONS_technical_documentation='UNVERSIONED' VERSIONS_technical_documentation='UNVERSIONED'
VERSIONS_website='UNVERSIONED' VERSIONS_website='UNVERSIONED'
VERSIONS_writers_toolkit='UNVERSIONED' VERSIONS_writers_toolkit='UNVERSIONED'
@ -237,8 +282,13 @@ PATHS_grafana_cloud='content/docs/grafana-cloud'
PATHS_helm_charts_mimir_distributed='docs/sources/helm-charts/mimir-distributed' PATHS_helm_charts_mimir_distributed='docs/sources/helm-charts/mimir-distributed'
PATHS_helm_charts_tempo_distributed='docs/sources/helm-charts/tempo-distributed' PATHS_helm_charts_tempo_distributed='docs/sources/helm-charts/tempo-distributed'
PATHS_mimir='docs/sources/mimir' PATHS_mimir='docs/sources/mimir'
PATHS_plugins_grafana_datadog_datasource='docs/sources'
PATHS_plugins_grafana_jira_datasource='docs/sources'
PATHS_plugins_grafana_mongodb_datasource='docs/sources'
PATHS_plugins_grafana_oracle_datasource='docs/sources'
PATHS_plugins_grafana_splunk_datasource='docs/sources'
PATHS_tempo='docs/sources/tempo' PATHS_tempo='docs/sources/tempo'
PATHS_website='content/docs' PATHS_website='content'
# identifier STR # identifier STR
# Replace characters that are not valid in an identifier with underscores. # Replace characters that are not valid in an identifier with underscores.
@ -253,6 +303,77 @@ aget() {
eval echo '$'"$(identifier "$1")_$(identifier "$2")" eval echo '$'"$(identifier "$1")_$(identifier "$2")"
} }
# src returns the project source repository name for a project.
src() {
_project="$1"
case "${_project}" in
plugins/*)
if [ -z "$(aget SOURCES "${_project}")" ]; then
echo plugins-private
else
aget SOURCES "${_project}"
fi
;;
*)
if [ -z "$(aget SOURCES "${_project}")" ]; then
echo "${_project}"
else
aget SOURCES "${_project}"
fi
;;
esac
unset _project
}
# path returns the relative path within the repository that contain the docs for a project.
path() {
_project="$1"
case "${_project}" in
plugins/*)
if [ -z "$(aget PATHS "${_project}")" ]; then
echo "${_project}/docs/sources"
else
aget PATHS "${_project}"
fi
;;
*)
if [ -z "$(aget PATHS "${_project}")" ]; then
echo "docs/sources"
else
aget PATHS "${_project}"
fi
esac
unset _project
}
# version returns the version for a project. Unversioned projects return the special value 'UNVERSIONED'.
version() {
_project="$1"
case "${_project}" in
plugins/*)
if [ -z "$(aget VERSIONS "${_project}")" ]; then
echo "UNVERSIONED"
else
aget VERSIONS "${_project}"
fi
;;
*)
if [ -z "$(aget VERSIONS "${_project}")" ]; then
echo latest
else
aget VERSIONS "${_project}"
fi
esac
unset _project
}
# new_proj populates a new project structure. # new_proj populates a new project structure.
new_proj() { new_proj() {
_project="$1" _project="$1"
@ -263,31 +384,19 @@ new_proj() {
# If version is not set, use the script mapping of project to default versions if it exists. # If version is not set, use the script mapping of project to default versions if it exists.
# Fallback to 'latest'. # Fallback to 'latest'.
if [ -z "${_version}" ]; then if [ -z "${_version}" ]; then
if [ -z "$(aget VERSIONS "${_project}")" ]; then _version="$(version "${_project}")"
_version=latest
else
_version="$(aget VERSIONS "${_project}")"
fi
fi fi
# If repo is not set, use the script mapping of project to repo name if it exists. # If repo is not set, use the script mapping of project to repo name if it exists.
# Fallback to using the project name. # Fallback to using the project name.
if [ -z "${_repo}" ]; then if [ -z "${_repo}" ]; then
if [ -z "$(aget SOURCES "${_project}")" ]; then _repo="$(src "${_project}")"
_repo="${_project}"
else
_repo="$(aget SOURCES "${_project}")"
fi
fi fi
# If path is not set, use the script mapping of project to docs sources path if it exists. # If path is not set, use the script mapping of project to docs sources path if it exists.
# Fallback to using 'docs/sources'. # Fallback to using 'docs/sources'.
if [ -z "${_path}" ]; then if [ -z "${_path}" ]; then
if [ -z "$(aget PATHS "${_project}")" ]; then _path="$(path "${_project}")"
_path="docs/sources"
else
_path="$(aget PATHS "${_project}")"
fi
fi fi
echo "${_project}:${_version}:${_repo}:${_path}" echo "${_project}:${_version}:${_repo}:${_path}"
@ -336,7 +445,7 @@ $1
POSIX_HERESTRING POSIX_HERESTRING
if [ "${_project}" = 'website' ]; then if [ "${_project}" = 'website' ]; then
echo '/hugo/content/docs' echo '/hugo/content'
unset _project _version unset _project _version
return return
@ -481,7 +590,7 @@ POSIX_HERESTRING
fi fi
done done
echo echo
echo 'Press Ctrl+c to stop the server' echo 'Press Ctrl+C to stop the server'
unset i max req url unset i max req url
return return
@ -490,7 +599,7 @@ POSIX_HERESTRING
echo echo
errr 'The build was interrupted or a build error occurred, check the previous logs for possible causes.' errr 'The build was interrupted or a build error occurred, check the previous logs for possible causes.'
note 'You might need to use Ctrl+c to end the process.' note 'You might need to use Ctrl+C to end the process.'
unset i max req url unset i max req url
} }
@ -519,10 +628,12 @@ for arg in "$@"; do
${arg} ${arg}
POSIX_HERESTRING POSIX_HERESTRING
if [ "${_project}" = website ]; then if [ "${_project}" = website ]; then
note "Please be patient, building the website can take some time."
_repo="$(repo_path website)" _repo="$(repo_path website)"
volumes="--volume=${_repo}/config:/hugo/config" volumes="--volume=${_repo}/config:/hugo/config"
volumes="${volumes} --volume=${_repo}/layouts/partials:/hugo/layouts/partials" volumes="${volumes} --volume=${_repo}/layouts:/hugo/layouts"
volumes="${volumes} --volume=${_repo}/layouts/shortcodes:/hugo/layouts/shortcodes" volumes="${volumes} --volume=${_repo}/scripts:/hugo/scripts"
fi fi
unset _project _repo unset _project _repo
done done
@ -540,7 +651,7 @@ POSIX_HERESTRING
fi fi
fi fi
debg "DEBG: Mounting '${_src}' at container path '${_dst}'" debg "Mounting '${_src}' at container path '${_dst}'"
if [ -z "${volumes}" ]; then if [ -z "${volumes}" ]; then
volumes="--volume=${_src}:${_dst}" volumes="--volume=${_src}:${_dst}"
@ -569,7 +680,6 @@ case "${image}" in
"${PODMAN}" run \ "${PODMAN}" run \
--init \ --init \
--interactive \ --interactive \
--name "${DOCS_CONTAINER}" \
--platform linux/amd64 \ --platform linux/amd64 \
--rm \ --rm \
--tty \ --tty \
@ -586,7 +696,6 @@ case "${image}" in
"${PODMAN}" run \ "${PODMAN}" run \
--init \ --init \
--interactive \ --interactive \
--name "${DOCS_CONTAINER}" \
--platform linux/amd64 \ --platform linux/amd64 \
--rm \ --rm \
--tty \ --tty \
@ -601,6 +710,12 @@ case "${image}" in
tempfile="$(mktemp -t make-docs.XXX)" tempfile="$(mktemp -t make-docs.XXX)"
cat <<EOF >"${tempfile}" cat <<EOF >"${tempfile}"
#!/usr/bin/env bash #!/usr/bin/env bash
tc() {
set \${*,,}
echo \${*^}
}
for redirect in ${redirects}; do for redirect in ${redirects}; do
IFS='^' read -r path ver <<<"\${redirect}" IFS='^' read -r path ver <<<"\${redirect}"
echo -e "---\\nredirectURL: \"\${path/\/hugo\/content/}\"\\ntype: redirect\\nversioned: true\\n---\\n" > "\${path/\${ver}/_index.md}" echo -e "---\\nredirectURL: \"\${path/\/hugo\/content/}\"\\ntype: redirect\\nversioned: true\\n---\\n" > "\${path/\${ver}/_index.md}"
@ -609,8 +724,12 @@ done
for x in "${url_src_dst_vers}"; do for x in "${url_src_dst_vers}"; do
IFS='^' read -r _ _ dst _ <<<"\${x}" IFS='^' read -r _ _ dst _ <<<"\${x}"
title="\${dst%/*}"
title="\$(tc \${title##*/})"
while [[ -n "\${dst}" ]]; do while [[ -n "\${dst}" ]]; do
touch "\${dst}/_index.md" if [[ ! -f "\${dst}/_index.md" ]]; then
echo -e "---title: \${title}\\n---\\n\\n# \${title}\\n\\n{{< section >}}" > "\${dst}/_index.md"
fi
dst="\${dst%/*}" dst="\${dst%/*}"
done done
done done
@ -630,22 +749,26 @@ ${PODMAN} run \
--env=HUGO_REFLINKSERRORLEVEL=${HUGO_REFLINKSERRORLEVEL} \ --env=HUGO_REFLINKSERRORLEVEL=${HUGO_REFLINKSERRORLEVEL} \
--init \ --init \
--interactive \ --interactive \
--name=${DOCS_CONTAINER} \
--platform=linux/amd64 \
--publish=${DOCS_HOST_PORT}:3002 \ --publish=${DOCS_HOST_PORT}:3002 \
--publish=3003:3003 \ --publish=3003:3003 \
--rm \ --rm \
--tty \ --tty \
${volumes} \ ${volumes} \
${DOCS_IMAGE} \ ${DOCS_IMAGE}
/entrypoint
EOF EOF
if [ -n "${ENTER}" ]; then
${cmd} /bin/bash
elif [ -n "${DEBUG}" ]; then
await_build http://localhost:3003 & await_build http://localhost:3003 &
if [ -n "${DEBUG}" ]; then debg "${cmd} /entrypoint"
${cmd} ${cmd} /entrypoint
else else
${cmd} 2>&1| sed \ await_build http://localhost:3003 &
${cmd} /entrypoint 2>&1\
| sed -u \
-e '/Web Server is available at http:\/\/localhost:3003\/ (bind address 0.0.0.0)/ d' \ -e '/Web Server is available at http:\/\/localhost:3003\/ (bind address 0.0.0.0)/ d' \
-e '/^hugo server/ d' \ -e '/^hugo server/ d' \
-e '/fatal: not a git repository (or any parent up to mount point \/)/ d' \ -e '/fatal: not a git repository (or any parent up to mount point \/)/ d' \
@ -656,7 +779,7 @@ EOF
-e '/website-proxy/ d' \ -e '/website-proxy/ d' \
-e '/rm -rf dist*/ d' \ -e '/rm -rf dist*/ d' \
-e '/Press Ctrl+C to stop/ d' \ -e '/Press Ctrl+C to stop/ d' \
-e '/make/ d' || echo -e '/make/ d'
fi fi
;; ;;
esac esac

Write Preview
Loading…
Cancel
Save