Update make docs procedure and ensure that it is regularly updated …

…in future. (#4450) * Add myself as CODEOWNER of `make docs` and related files via @grafana/tooling team Signed-off-by: Jack Baldry <[email protected]> * Add workflow to automatically update `make docs` procedure daily Signed-off-by: Jack Baldry <[email protected]> * Update `make docs` procedure Signed-off-by: Jack Baldry <[email protected]> --------- Signed-off-by: Jack Baldry <[email protected]>
grafana · Aug 14, 2023 · 9658607 · 9658607
1 parent f3a812f
commit 9658607
Show file tree

Hide file tree

Showing 5 changed files with 86 additions and 24 deletions.
diff --git a/.github/workflows/update-make-docs.yml b/.github/workflows/update-make-docs.yml
@@ -0,0 +1,27 @@
+name: Update `make docs` procedure
+on:
+  schedule:
+    - cron: '0 7 * * 1-5'
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Update procedure
+        if: github.repository != 'grafana/writers-toolkit'
+        run: |
+          curl -s -Lo docs/docs.mk https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
+          curl -s -Lo docs/make-docs https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
+          if git diff --exit-code; then exit 0; fi
+          BRANCH="$(date +%Y-%m-%d)/update-make-docs"
+          git checkout -b "${BRANCH}"
+          git add .
+          git config --local user.email "[email protected]"
+          git config --local user.name "grafanabot"
+          git commit -m "Update \`make docs\` procedure"
+          git push -v origin "refs/heads/${BRANCH}"
+          gh pr create --fill
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -21,6 +21,14 @@
 # Binaries:
 /cmd/grafana-agent-operator/  @grafana/grafana-agent-operator-maintainers
 
+# `make docs` procedure and related workflows are owned @grafana/docs-tooling. Slack #docs.
+/.github/workflows/publish-technical-documentation-next.yml    @grafana/docs-tooling
+/.github/workflows/publish-technical-documentation-release.yml @grafana/docs-tooling
+/.github/workflows/update-make-docs.yml                        @grafana/docs-tooling
+/docs/docs.mk                                                  @grafana/docs-tooling
+/docs/make-docs                                                @grafana/docs-tooling
+/docs/variables.mk                                             @grafana/docs-tooling
+
 # Documentation:
 /docs/sources/  @clayton-cornell
 

diff --git a/docs/docs.mk b/docs/docs.mk
@@ -1,5 +1,5 @@
 # The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk.
-# 1.2.1 (2023-05-05)
+# 4.0.0 (2023-06-06)
 include variables.mk
 -include variables.mk.local
 
@@ -105,11 +105,6 @@ doc-validator: ## Run doc-validator on the entire docs folder.
 doc-validator: make-docs
 	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(PWD)/make-docs $(PROJECTS)
 
-.PHONY: doc-validator/%
-doc-validator/%: ## Run doc-validator on a specific path. To lint the path /docs/sources/administration, run 'make doc-validator/administration'.
-doc-validator/%: make-docs
-	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) DOC_VALIDATOR_INCLUDE=$(subst doc-validator/,,$@) $(PWD)/make-docs $(PROJECTS)
-
 .PHONY: vale
 vale: ## Run vale on the entire docs folder.
 vale: make-docs

diff --git a/docs/make-docs b/docs/make-docs
@@ -1,6 +1,6 @@
 #!/bin/sh
 # The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs.
-# 1.2.1 (2023-05-05)
+# 4.1.0 (2023-06-16)
 
 set -ef
 
@@ -9,10 +9,11 @@ readonly DOCS_HOST_PORT="${DOCS_HOST_PORT:-3002}"
 readonly DOCS_IMAGE="${DOCS_IMAGE:-grafana/docs-base:latest}"
 
 readonly DOC_VALIDATOR_INCLUDE="${DOC_VALIDATOR_INCLUDE:-.+\.md$}"
+readonly DOC_VALIDATOR_SKIP_CHECKS="${DOC_VALIDATOR_SKIP_CHECKS:-^image-}"
 
 readonly HUGO_REFLINKSERRORLEVEL="${HUGO_REFLINKSERRORLEVEL:-WARNING}"
 readonly VALE_MINALERTLEVEL="${VALE_MINALERTLEVEL:-error}"
-readonly WEBSITE_EXEC="${WEBSITE_EXEC:-make docs}"
+readonly WEBSITE_EXEC="${WEBSITE_EXEC:-make server-docs}"
 # If set, the docs-base image will run a prebuild script that sets up Hugo mounts.
 readonly WEBSITE_MOUNTS="${WEBSITE_MOUNTS:-}"
 
@@ -62,20 +63,23 @@ SOURCES_as_code='as-code-docs'
 SOURCES_enterprise_metrics='backend-enterprise'
 SOURCES_enterprise_metrics_='backend-enterprise'
 SOURCES_grafana_cloud='website'
+SOURCES_grafana_cloud_alerting_and_irm_machine_learning='machine-learning'
+SOURCES_grafana_cloud_alerting_and_irm_slo='slo'
 SOURCES_grafana_cloud_k6='k6-docs'
 SOURCES_grafana_cloud_data_configuration_integrations='cloud-onboarding'
 SOURCES_grafana_cloud_frontend_observability_faro_web_sdk='faro-web-sdk'
-SOURCES_grafana_cloud_machine_learning='machine-learning'
 SOURCES_helm_charts_mimir_distributed='mimir'
 SOURCES_helm_charts_tempo_distributed='tempo'
 SOURCES_opentelemetry='opentelemetry-docs'
+SOURCES_plugins_grafana_splunk_datasource='splunk-datasource'
 
 VERSIONS_as_code='UNVERSIONED'
 VERSIONS_grafana_cloud='UNVERSIONED'
+VERSIONS_grafana_cloud_alerting_and_irm_machine_learning='UNVERSIONED'
+VERSIONS_grafana_cloud_alerting_and_irm_slo='UNVERSIONED'
 VERSIONS_grafana_cloud_k6='UNVERSIONED'
 VERSIONS_grafana_cloud_data_configuration_integrations='UNVERSIONED'
 VERSIONS_grafana_cloud_frontend_observability_faro_web_sdk='UNVERSIONED'
-VERSIONS_grafana_cloud_machine_learning='UNVERSIONED'
 VERSIONS_opentelemetry='UNVERSIONED'
 VERSIONS_technical_documentation='UNVERSIONED'
 VERSIONS_website='UNVERSIONED'
@@ -199,18 +203,14 @@ POSIX_HERESTRING
   unset _project _version
 }
 
-# proj_src returns the host path to content source for a project.
-# It expects a complete project structure as input.
+# repo_path returns the host path to the project repository.
 # It looks for the provided repository name in each of the paths specified in the REPOS_PATH environment variable.
-proj_src() {
-  IFS=: read -r _ _ _repo _path <<POSIX_HERESTRING
-$1
-POSIX_HERESTRING
-
+repo_path() {
+  _repo="$1"
   IFS=:
   for lookup in ${REPOS_PATH}; do
     if [ -d "${lookup}/${_repo}" ]; then
-      echo "${lookup}/${_repo}/${_path}"
+      echo "${lookup}/${_repo}"
       unset _path _repo
       return
     fi
@@ -220,10 +220,24 @@ POSIX_HERESTRING
   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
-  unset _path _repo
+  unset _repo
   exit 1
 }
 
+# proj_src returns the host path to content source for a project.
+# It expects a complete project structure as input.
+# It looks for the provided repository name in each of the paths specified in the REPOS_PATH environment variable.
+proj_src() {
+  IFS=: read -r _ _ _repo _path <<POSIX_HERESTRING
+$1
+POSIX_HERESTRING
+
+  _repo="$(repo_path "${_repo}")"
+  echo "${_repo}/${_path}"
+
+  unset _path _repo
+}
+
 # proj_canonical returns the canonical absolute path partial URI for a project.
 # It expects a complete project structure as input.
 proj_canonical() {
@@ -296,6 +310,19 @@ url_src_dst_vers="$(url_src_dst_vers "$@")"
 volumes=""
 redirects=""
 
+for arg in "$@"; do
+  IFS=: read -r _project _ _repo _ <<POSIX_HERESTRING
+${arg}
+POSIX_HERESTRING
+  if [ "${_project}" = website ]; then
+    _repo="$(repo_path website)"
+    volumes="--volume=${_repo}/config:/hugo/config"
+    volumes="${volumes} --volume=${_repo}/layouts/partials:/hugo/layouts/partials"
+    volumes="${volumes} --volume=${_repo}/layouts/shortcodes:/hugo/layouts/shortcodes"
+  fi
+  unset _project _repo
+done
+
 for x in ${url_src_dst_vers}; do
   IFS='^' read -r _url _src _dst _ver <<POSIX_HERESTRING
 $x
@@ -343,8 +370,8 @@ case "${image}" in
       --tty \
       ${volumes} \
       "${DOCS_IMAGE}" \
-      --skip-image-validation \
-      --include="${DOC_VALIDATOR_INCLUDE}" \
+      "--include=${DOC_VALIDATOR_INCLUDE}" \
+      "--skip-checks=${DOC_VALIDATOR_SKIP_CHECKS}" \
       /hugo/content/docs \
       "$(proj_canonical "${proj}")" | sed "s#$(proj_dst "${proj}")#sources#"
     ;;
@@ -360,7 +387,7 @@ case "${image}" in
       --tty \
       ${volumes} \
       "${DOCS_IMAGE}" \
-      --minAlertLevel="${VALE_MINALERTLEVEL}" \
+      "--minAlertLevel=${VALE_MINALERTLEVEL}" \
       --config=/etc/vale/.vale.ini \
       --output=line \
       /hugo/content/docs | sed "s#$(proj_dst "${proj}")#sources#"
@@ -371,7 +398,7 @@ case "${image}" in
 #!/usr/bin/env bash
 for redirect in ${redirects}; do
   IFS='^' read -r path ver <<<"\${redirect}"
-  echo -e "---\\nredirectURL: \"\${path/\/hugo\/content/}\"\\ntype: redirect\\n---\\n" > "\${path/\${ver}/_index.md}"
+  echo -e "---\\nredirectURL: \"\${path/\/hugo\/content/}\"\\ntype: redirect\\nversioned: true\\n---\\n" > "\${path/\${ver}/_index.md}"
 done
 
 for x in "${url_src_dst_vers}"; do

diff --git a/docs/variables.mk b/docs/variables.mk
@@ -1,2 +1,7 @@
 # List of projects to provide to the make-docs script.
-PROJECTS = agent
+# Format is PROJECT[:[VERSION][:[REPOSITORY][:[DIRECTORY]]]]
+# The following PROJECTS value mounts content into the agent project, at the "latest" version, which is the default if not explicitly set.
+# This results in the content being served at /docs/agent/latest/.
+# The source of the content is the current repository which is determined by the name of the parent directory of the git root.
+# This overrides the default behavior of assuming the repository directory is the same as the project name.
+PROJECTS := agent::$(notdir $(basename $(shell git rev-parse --show-toplevel)))