From 72e8bdfdad6b11c3d8de39bfb26ab16171f81ef1 Mon Sep 17 00:00:00 2001 From: Pranshu Srivastava Date: Wed, 1 Nov 2023 07:16:10 +0530 Subject: [PATCH] *: content revamp These changes mostly entail: * workflow to check for new theme releases, * improved synchronization logic, * better reference defintions in generated content, * serve minified JS, * higher degree of automation. Fixes: https://github.com/prometheus-operator/prometheus-operator/issues/6046 Signed-off-by: Pranshu Srivastava --- .github/workflows/hugo-theme-release.yml | 26 +++++ .gitignore | 37 +++---- Makefile | 20 ++-- config.yaml | 5 - synchronize.sh | 126 +++++++++++++++-------- 5 files changed, 135 insertions(+), 79 deletions(-) create mode 100644 .github/workflows/hugo-theme-release.yml diff --git a/.github/workflows/hugo-theme-release.yml b/.github/workflows/hugo-theme-release.yml new file mode 100644 index 0000000..827f9e6 --- /dev/null +++ b/.github/workflows/hugo-theme-release.yml @@ -0,0 +1,26 @@ +name: Hugo Theme Release + +on: + schedule: + # Check every week. + - cron: '0 0 * * 0' + +jobs: + check-theme-release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Check for new theme release + run: | + # Get the latest release tag downstream. + cd themes/doks + git fetch --tags + latest_tag=$(git describe --tags `git rev-list --tags --max-count=1` | cut -d. -f1) + current_tag=$(git describe --tags | cut -d. -f1) + if [ "$latest_tag" != "$current_tag" ]; then + repository=$(git config --get remote.origin.url) + echo "[OUTDATED] $repository: $latest_tag/$current_tag" + exit 1 + else + echo "[UP-TO-DATE] No new theme release available." + fi diff --git a/.gitignore b/.gitignore index be161df..e35a33b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +# Build artifacts to ignore. + /public/ /repos/kube-prometheus /repos/prometheus-operator @@ -5,31 +7,16 @@ /static/img /.hugo_build.lock -# Generated content to ignore (sorted alphabetically) +# Generated content to ignore. /content/adopters.md -/content/docs/kube/developing-prometheus-rules-and-grafana-dashboards.md -/content/docs/kube/exposing-prometheus-alertmanager-grafana-ingress.md -/content/docs/kube/kube-prometheus-on-kubeadm.md -/content/docs/kube/blackbox-exporter.md -/content/docs/kube/deploy-kind.md -/content/docs/kube/monitoring-external-etcd.md -/content/docs/kube/monitoring-other-namespaces.md -/content/docs/user-guides/getting-started.md -/content/docs/user-guides/alerting.md -/content/docs/user-guides/webhook.md -/content/docs/user-guides/prometheus-agent.md -/content/docs/user-guides/scrapeconfig.md -/content/docs/operator/api.md -/content/docs/operator/compatibility.md -/content/docs/operator/custom-metrics-elements.png -/content/docs/operator/design.md -/content/docs/operator/high-availability.md -/content/docs/operator/operator.md -/content/docs/operator/rbac-crd.md -/content/docs/operator/rbac.md -/content/docs/operator/storage.md -/content/docs/operator/strategic-merge-patch.md -/content/docs/operator/thanos.md -/content/docs/operator/troubleshooting.md +/content/docs/kube/* +/content/docs/operator/* /content/docs/prologue/contributing.md +/content/docs/user-guides/* + +# Exempt _index.md files from the above rules. + +!/content/docs/kube/_index.md +!/content/docs/operator/_index.md +!/content/docs/user-guides/_index.md diff --git a/Makefile b/Makefile index 9198514..c439d3c 100644 --- a/Makefile +++ b/Makefile @@ -1,15 +1,19 @@ -all: theme synchronize public - -.PHONY: synchronize -synchronize: - bash synchronize.sh +all: theme synchronize build .PHONY: theme theme: - cd themes/doks/ && \ + @cd themes/doks/ && \ npm install && \ rm -rf content -.PHONY: public -public: +.PHONY: synchronize +synchronize: + bash -x synchronize.sh + +.PHONY: build +build: hugo + +.PHONY: serve +serve: + hugo serve diff --git a/config.yaml b/config.yaml index c7c9b8c..8f6d6aa 100644 --- a/config.yaml +++ b/config.yaml @@ -3,8 +3,3 @@ languageCode: "en-us" title: "Prometheus Operator" theme: doks - -# Disable minification of JS code to workaround -# https://github.com/h-enk/doks/issues/716 -minify: - disableJS: true diff --git a/synchronize.sh b/synchronize.sh index 939f272..294922d 100755 --- a/synchronize.sh +++ b/synchronize.sh @@ -1,54 +1,98 @@ #!/usr/bin/env bash -set -xe +# -e: Exit immediately if a command exits with a non-zero status. +# -o pipefail: Causes a pipeline to return the exit status of the last command in the pipe that returned a non-zero return value. +set -eo pipefail +# Remove artefacts. rm -rf repos/ + +# Create directories. mkdir repos/ -if [[ -z "$USE_LOCAL_REPOSITORIES" ]]; then +# Clone repos or use local copies. +if [[ -n "$PO_PATH" ]] && [[ -d "$PO_PATH" ]]; then + ln -s "$PO_PATH" repos/prometheus-operator +else git clone https://github.com/prometheus-operator/prometheus-operator -b main --depth 1 repos/prometheus-operator - git clone https://github.com/prometheus-operator/kube-prometheus -b main --depth 1 repos/kube-prometheus +fi + +if [[ -n "$KUBE_PROMETHEUS_PATH" ]] && [[ -d "$KUBE_PROMETHEUS_PATH" ]]; then + ln -s "$KUBE_PROMETHEUS_PATH" repos/kube-prometheus else - ln -s ../../prometheus-operator repos/prometheus-operator - ln -s ../../kube-prometheus repos/kube-prometheus + git clone https://github.com/prometheus-operator/kube-prometheus -b main --depth 1 repos/kube-prometheus fi +# Show pinned revisions. for r in repos/prometheus-operator repos/kube-prometheus; do - echo "$r -> ""$(cd $r && git rev-parse HEAD)" + echo "$r@""$(cd $r && git rev-parse HEAD)" +done + +# Copy dependant sections and metadata. +cp -f repos/prometheus-operator/ADOPTERS.md content/adopters.md +cp -f repos/prometheus-operator/CONTRIBUTING.md content/docs/prologue/contributing.md +cp -fr repos/prometheus-operator/Documentation/img static/img +cp -fr repos/prometheus-operator/Documentation/user-guides/ content/docs/user-guides/ +cp -fr repos/prometheus-operator/Documentation/ content/docs/operator/ +cp -fr repos/kube-prometheus/docs/ content/docs/kube/ + +# One-off fixes so as to not break links. +cp -f repos/prometheus-operator/Documentation/user-guides/storage.md content/docs/operator/storage.md +cp -f repos/prometheus-operator/Documentation/user-guides/strategic-merge-patch.md content/docs/operator/strategic-merge-patch.md +cp -f repos/kube-prometheus/docs/customizations/developing-prometheus-rules-and-grafana-dashboards.md content/docs/kube/developing-prometheus-rules-and-grafana-dashboards.md +cp -f repos/kube-prometheus/docs/customizations/exposing-prometheus-alertmanager-grafana-ingress.md content/docs/kube/exposing-prometheus-alertmanager-grafana-ingress.md + + + +# Remove invalid files without front matter. +find content/docs -type f -name "*.md" -print0 | while IFS= read -r -d '' file; do + # Prevent awk from failing the script if the file is empty. + set +e + # For each line in the file: + # * BEGIN: Set p to 0 and exitcode to 0. + # * !p && NF: If p is 0 and the number of fields is not 0 (i.e. the line is not empty): + # * if ($0 != "---"): If the line is not "---", set exitcode to 1 and exit. + # * else: Set p to 1 and skip to the next line. + # * p && /---/: If p is 1 and the line is "---", set p to 2. + # * END: If p is not 2, set exitcode to 1. + # Note how p is used to move from the first part of the conditional to the next (p && ..., otherwise it will keep checking the first condition until EOF). + awk 'BEGIN {p=0; exitcode=0} !p && NF { if ($0 != "---") {exitcode=1; exit} else {p=1; next} } p && /---/ {p=2} END {if (p != 2) exitcode=1; exit exitcode}' "${file}" > /dev/null + EXITCODE=$? + set -e + # Prepend zero-length front matter if the file is invalid. + if [ "$EXITCODE" -ne 0 ]; then + TMPFILE=$(mktemp) + TITLE=$(\ + # Remove .md extension. + basename "${file}" .md |\ + # Replace dashes with spaces. + sed 's/-/ /g' |\ + # First, positive lookbehind from non-whitespace character for a whitespace. + # Then, convert each word to lowercase. + # Finally, convert the first letter of each word to uppercase and add a whitespace. + perl -ne 'print ucfirst(lc($_))." " for split /(?<=\S)\s+/') + echo -e "---\ntitle: ${TITLE}\n---\n" > "$TMPFILE" + cat "$file" >> "$TMPFILE" + mv "$TMPFILE" "$file" + fi +done + +# Prevent grep from failing the script. +set +e + +# Sanitize links by replacing immediate filenames with relative (to /docs references). +find ./content/docs -name "*.md" | while IFS= read -r file +do + # Extract markdown links (in the format [text](link.md)) from the current file. + grep -oE '\]\([^/)]*\.md\)' "${file}" | while IFS= read -r link + do + dirName=$(dirname "${file}") + sanitizedLink=$(echo "${link}" | tr -d "]()" | sed 's/\.md//') + original="](${sanitizedLink}.md)" + sanitizedLinkWithPath="${dirName}/${sanitizedLink}" + modified="](/docs/${sanitizedLinkWithPath#./content/docs/}/)" + sed -i '' -e "s|${original}|${modified}|g" "${file}" + done done -# main section + images -cp repos/prometheus-operator/ADOPTERS.md content/adopters.md -cp -r repos/prometheus-operator/Documentation/img static/img - -# prologue section -cp repos/prometheus-operator/CONTRIBUTING.md content/docs/prologue/contributing.md - -# user guides section -cp repos/prometheus-operator/Documentation/user-guides/getting-started.md content/docs/user-guides/getting-started.md -cp repos/prometheus-operator/Documentation/user-guides/alerting.md content/docs/user-guides/alerting.md -cp repos/prometheus-operator/Documentation/user-guides/prometheus-agent.md content/docs/user-guides/prometheus-agent.md -cp repos/prometheus-operator/Documentation/user-guides/scrapeconfig.md content/docs/user-guides/scrapeconfig.md -cp repos/prometheus-operator/Documentation/user-guides/webhook.md content/docs/user-guides/webhook.md - -# prometheus-operator section -cp repos/prometheus-operator/Documentation/api.md content/docs/operator/api.md -cp repos/prometheus-operator/Documentation/operator.md content/docs/operator/operator.md -cp repos/prometheus-operator/Documentation/compatibility.md content/docs/operator/compatibility.md -cp repos/prometheus-operator/Documentation/design.md content/docs/operator/design.md -cp repos/prometheus-operator/Documentation/high-availability.md content/docs/operator/high-availability.md -cp repos/prometheus-operator/Documentation/rbac-crd.md content/docs/operator/rbac-crd.md -cp repos/prometheus-operator/Documentation/rbac.md content/docs/operator/rbac.md -cp repos/prometheus-operator/Documentation/thanos.md content/docs/operator/thanos.md -cp repos/prometheus-operator/Documentation/troubleshooting.md content/docs/operator/troubleshooting.md -cp repos/prometheus-operator/Documentation/user-guides/storage.md content/docs/operator/storage.md -cp repos/prometheus-operator/Documentation/user-guides/strategic-merge-patch.md content/docs/operator/strategic-merge-patch.md - -# kube-prometheus section -cp repos/kube-prometheus/docs/blackbox-exporter.md content/docs/kube/blackbox-exporter.md -cp repos/kube-prometheus/docs/deploy-kind.md content/docs/kube/deploy-kind.md -cp repos/kube-prometheus/docs/customizations/developing-prometheus-rules-and-grafana-dashboards.md content/docs/kube/developing-prometheus-rules-and-grafana-dashboards.md -cp repos/kube-prometheus/docs/customizations/exposing-prometheus-alertmanager-grafana-ingress.md content/docs/kube/exposing-prometheus-alertmanager-grafana-ingress.md -cp repos/kube-prometheus/docs/kube-prometheus-on-kubeadm.md content/docs/kube/kube-prometheus-on-kubeadm.md -cp repos/kube-prometheus/docs/monitoring-external-etcd.md content/docs/kube/monitoring-external-etcd.md -cp repos/kube-prometheus/docs/monitoring-other-namespaces.md content/docs/kube/monitoring-other-namespaces.md +set -e