Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update make docs procedure #24

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update make docs procedure #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/docs.mk
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ docs-rm: ## Remove the docs container.

.PHONY: docs-pull
docs-pull: ## Pull documentation base image.
$(PODMAN) pull $(DOCS_IMAGE)
$(PODMAN) pull -q $(DOCS_IMAGE)

make-docs: ## Fetch the latest make-docs script.
make-docs:
Expand Down
191 changes: 131 additions & 60 deletions docs/make-docs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,11 @@
# [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.

# ## Unreleased
# ## 4.1.1 (2023-07-20)

# ### Fixed

# - Replaced use of `realpath` with POSIX compatible alternative to determine default value for REPOS_PATH.

# ## 4.1.0 (2023-06-16)

Expand Down Expand Up @@ -129,6 +133,21 @@ readonly WEBSITE_MOUNTS="${WEBSITE_MOUNTS:-}"

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
if ! command -v wget >/dev/null 2>&1; then
errr 'either `curl` or `wget` must be installed for this script to work.'

exit 1
fi
fi

if ! command -v "${PODMAN}" >/dev/null 2>&1; then
errr 'either `podman` or `docker` must be installed for this script to work.'

exit 1
fi


about() {
cat <<EOF
Test documentation locally with multiple source repositories.
Expand Down Expand Up @@ -158,7 +177,7 @@ EOF
exit 1
fi

readonly REPOS_PATH="${REPOS_PATH:-$(realpath "$(git rev-parse --show-toplevel)/..")}"
readonly REPOS_PATH="${REPOS_PATH:-$(cd "$(git rev-parse --show-toplevel)/.." && echo "${PWD}")}"

if [ -z "${REPOS_PATH}" ]; then
cat <<EOF >&2
Expand All @@ -170,6 +189,7 @@ EOF
fi

SOURCES_as_code='as-code-docs'
SOURCES_beyla='ebpf-autoinstrument'
SOURCES_enterprise_metrics='backend-enterprise'
SOURCES_enterprise_metrics_='backend-enterprise'
SOURCES_grafana_cloud='website'
Expand Down Expand Up @@ -327,9 +347,10 @@ repo_path() {
done
unset IFS

echo "ERRR: could not find project '${_repo}' in any of the paths in REPOS_PATH '${REPOS_PATH}'." >&2
echo "NOTE: you must have a checkout of the project '${_repo}' at '${REPOS_PATH##:*}/${_repo}'." >&2
echo "NOTE: if you have cloned the repository into a directory with a different name, consider changing it to ${_repo}." >&2
errr "could not find project '${_repo}' in any of the paths in REPOS_PATH '${REPOS_PATH}'."
note "you must have a checkout of the project '${_repo}' at '${REPOS_PATH##:*}/${_repo}'."
note "if you have cloned the repository into a directory with a different name, consider changing it to ${_repo}."

unset _repo
exit 1
}
Expand Down Expand Up @@ -415,6 +436,50 @@ POSIX_HERESTRING
unset _project _version _repo _path
}

await_build() {
url="$1"
req="$(if command -v curl >/dev/null 2>&1; then echo 'curl -s -o /dev/null'; else echo 'wget -q'; fi)"

sleep 2

if ${req} "${url}"; then
echo
echo "View documentation locally:"
for x in ${url_src_dst_vers}; do
IFS='^' read -r url _ _ <<POSIX_HERESTRING
$x
POSIX_HERESTRING

if [ -n "${url}" ]; then
if [ "${_url}" != "arbitrary" ]; then
echo " ${url}"
fi
fi
done
echo
echo 'Press Ctrl+C to stop the server'
else
echo
errr 'The build was interrupted or a build error occurred, check the previous logs for possible causes.'
fi

unset url req
}

debg() {
if [ -n "${DEBUG}" ]; then
echo "DEBG: $1" >&2
fi
}

errr() {
echo "ERRR: $1" >&2
}

note() {
echo "NOTE: $1" >&2
}

url_src_dst_vers="$(url_src_dst_vers "$@")"

volumes=""
Expand All @@ -440,13 +505,14 @@ POSIX_HERESTRING

if [ "${_url}" != "arbitrary" ]; then
if [ ! -f "${_src}/_index.md" ]; then
echo "ERRR: Index file '${_src}/_index.md' does not exist." >&2
echo "Is '${_src}' the correct source directory?" >&2
errr "Index file '${_src}/_index.md' does not exist."
note "Is '${_src}' the correct source directory?"
exit 1
fi
fi

echo "DEBG: Mounting '${_src}' at container path '${_dst}'" >&2
debg "DEBG: Mounting '${_src}' at container path '${_dst}'"

if [ -z "${volumes}" ]; then
volumes="--volume=${_src}:${_dst}"
else
Expand All @@ -472,35 +538,35 @@ case "${image}" in
proj="$(new_proj "$1")"
echo
"${PODMAN}" run \
--init \
--interactive \
--name "${DOCS_CONTAINER}" \
--platform linux/amd64 \
--rm \
--tty \
${volumes} \
"${DOCS_IMAGE}" \
"--include=${DOC_VALIDATOR_INCLUDE}" \
"--skip-checks=${DOC_VALIDATOR_SKIP_CHECKS}" \
/hugo/content/docs \
"$(proj_canonical "${proj}")" | sed "s#$(proj_dst "${proj}")#sources#"
--init \
--interactive \
--name "${DOCS_CONTAINER}" \
--platform linux/amd64 \
--rm \
--tty \
${volumes} \
"${DOCS_IMAGE}" \
"--include=${DOC_VALIDATOR_INCLUDE}" \
"--skip-checks=${DOC_VALIDATOR_SKIP_CHECKS}" \
/hugo/content/docs \
"$(proj_canonical "${proj}")" | sed "s#$(proj_dst "${proj}")#sources#"
;;
'grafana/vale')
proj="$(new_proj "$1")"
echo
"${PODMAN}" run \
--init \
--interactive \
--name "${DOCS_CONTAINER}" \
--platform linux/amd64 \
--rm \
--tty \
${volumes} \
"${DOCS_IMAGE}" \
"--minAlertLevel=${VALE_MINALERTLEVEL}" \
--config=/etc/vale/.vale.ini \
--output=line \
/hugo/content/docs | sed "s#$(proj_dst "${proj}")#sources#"
--init \
--interactive \
--name "${DOCS_CONTAINER}" \
--platform linux/amd64 \
--rm \
--tty \
${volumes} \
"${DOCS_IMAGE}" \
"--minAlertLevel=${VALE_MINALERTLEVEL}" \
--config=/etc/vale/.vale.ini \
--output=line \
/hugo/content/docs | sed "s#$(proj_dst "${proj}")#sources#"
;;
*)
tempfile="$(mktemp -t make-docs.XXX)"
Expand All @@ -527,36 +593,41 @@ fi
${WEBSITE_EXEC}
EOF
chmod +x "${tempfile}"
volumes="${volumes} --volume=$(realpath "${tempfile}"):/entrypoint"
volumes="${volumes} --volume=${tempfile}:/entrypoint"
readonly volumes

echo
echo "Documentation will be served at the following URLs:"
for x in ${url_src_dst_vers}; do
IFS='^' read -r url _ _ <<POSIX_HERESTRING
$x
POSIX_HERESTRING

if [ -n "${url}" ]; then
if [ "${_url}" != "arbitrary" ]; then
echo " ${url}"
fi
fi
done
IFS='' read -r cmd <<EOF
${PODMAN} run \
--env=HUGO_REFLINKSERRORLEVEL=${HUGO_REFLINKSERRORLEVEL} \
--init \
--interactive \
--name=${DOCS_CONTAINER} \
--platform=linux/amd64 \
--publish=${DOCS_HOST_PORT}:3002 \
--publish=3003:3003 \
--rm \
--tty \
${volumes} \
${DOCS_IMAGE} \
/entrypoint
EOF
await_build http://localhost:3002 &

echo
"${PODMAN}" run \
--env "HUGO_REFLINKSERRORLEVEL=${HUGO_REFLINKSERRORLEVEL}" \
--init \
--interactive \
--name "${DOCS_CONTAINER}" \
--platform linux/amd64 \
--publish "${DOCS_HOST_PORT}:3002" \
--publish "3003:3003" \
--rm \
--tty \
${volumes} \
"${DOCS_IMAGE}" \
/entrypoint
if [ -n "${DEBUG}" ]; then
${cmd}
else
${cmd} 2>&1| sed \
-e '/Web Server is available at http:\/\/localhost:3003\/ (bind address 0.0.0.0)/ d' \
-e '/^hugo server/ d' \
-e '/fatal: not a git repository (or any parent up to mount point \/)/ d' \
-e '/Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set)./ d' \
-e "/Makefile:[0-9]*: warning: overriding recipe for target 'docs'/ d" \
-e "/docs.mk:[0-9]*: warning: ignoring old recipe for target 'docs'/ d" \
-e '/\/usr\/bin\/make -j 2 proxy hserver-docs HUGO_PORT=3003/ d' \
-e '/website-proxy/ d' \
-e '/rm -rf dist*/ d' \
-e '/Press Ctrl+C to stop/ d' \
-e '/make/ d' || echo
fi
;;
esac