[v10.4.x] Update `make docs` procedure (#88408)

Co-authored-by: grafanabot <bot@grafana.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

docs/make-docs

@@ -6,6 +6,17 @@
 # [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
@@ -255,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
@@ -750,34 +763,72 @@ case "${image}" in
   'grafana/doc-validator')
     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/docs \
-                "$(proj_canonical "${proj}")" | sed "s#$(proj_dst "${proj}")#sources#"
+                ${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)"

docs/sources/release-notes/release-notes-8-2-0.md

@@ -34,7 +34,7 @@ title: Release notes for Grafana 8.2.0
 
 #### Potential failure to start in Ubuntu 18.04 / Debian 9 / CentOS
 
-- In Grafana v8.2.0, this change can prevent the `grafana-server` service from starting on older versions of systemd, present on Ubuntu 18.04 and slightly older versions of Debian. If running one of those versions, please wait until v8.2.1 is released before upgrading. If you still want to upgrade or have already ugpraded, a simple fix is available here: https://github.com/grafana/grafana/issues/40162#issuecomment-938060240 Issue [#38109](https://github.com/grafana/grafana/issues/38109)
+- In Grafana v8.2.0, this change can prevent the `grafana-server` service from starting on older versions of systemd, present on Ubuntu 18.04 and slightly older versions of Debian. If running one of those versions, please wait until v8.2.1 is released before upgrading. If you still want to upgrade or have already upgraded, a simple fix is available here: https://github.com/grafana/grafana/issues/40162#issuecomment-938060240 Issue [#38109](https://github.com/grafana/grafana/issues/38109)
 
 ### Plugin development fixes & changes
 

docs/sources/release-notes/release-notes-9-0-4.md

@@ -18,7 +18,7 @@ title: Release notes for Grafana 9.0.4
 - **Browse/Search:** Make browser back work properly when visiting Browse or search. [#52271](https://github.com/grafana/grafana/pull/52271), [@torkelo](https://github.com/torkelo)
 - **Logs:** Improve getLogRowContext API. [#52130](https://github.com/grafana/grafana/pull/52130), [@gabor](https://github.com/gabor)
 - **Loki:** Improve handling of empty responses. [#52397](https://github.com/grafana/grafana/pull/52397), [@gabor](https://github.com/gabor)
-- **Plugins:** Always validate root URL if specified in signature manfiest. [#52332](https://github.com/grafana/grafana/pull/52332), [@wbrowne](https://github.com/wbrowne)
+- **Plugins:** Always validate root URL if specified in signature manifest. [#52332](https://github.com/grafana/grafana/pull/52332), [@wbrowne](https://github.com/wbrowne)
 - **Preferences:** Get home dashboard from teams. [#52225](https://github.com/grafana/grafana/pull/52225), [@sakjur](https://github.com/sakjur)
 - **SQLStore:** Support Upserting multiple rows. [#52228](https://github.com/grafana/grafana/pull/52228), [@joeblubaugh](https://github.com/joeblubaugh)
 - **Traces:** Add more template variables in Tempo & Zipkin. [#52306](https://github.com/grafana/grafana/pull/52306), [@joey-grafana](https://github.com/joey-grafana)