Update make docs procedure and related workflows (#71537)

* Add myself as CODEOWNER for `make docs` procedure and related workflows

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Update `make docs` procedure

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Add workflow to update `make docs` procedure

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Update doc-validator workflow

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix team handle

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Clean up CODEOWNERS

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

---------

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

.github/CODEOWNERS

@@ -33,7 +33,9 @@
 /devenv/README.md @grafana/docs-grafana
 
 # Technical documentation
-/docs/                                    @Eve832 @jdbaldry
+# `make docs` procedure and related workflows are owned @grafana/docs-tooling. Slack #docs.
+# Documentation sources might have different owners.
+/docs/                                                                       @grafana/docs-tooling
 /docs/sources/                                                               @Eve832
 /docs/sources/administration/                                                @Eve832 @GrafanaWriter
 /docs/sources/alerting/                                                      @brendamuir
@@ -596,7 +598,7 @@ embed.go @grafana/grafana-as-code
 /.github/workflows/codeql-analysis.yml @DanCech
 /.github/workflows/commands.yml @torkelo
 /.github/workflows/detect-breaking-changes-* @grafana/plugins-platform-frontend
-/.github/workflows/doc-validator.yml @grafana/docs-grafana
+/.github/workflows/doc-validator.yml @grafana/docs-tooling
 /.github/workflows/epic-add-to-platform-ux-parent-project.yml @meanmina
 /.github/workflows/github-release.yml @torkelo
 /.github/workflows/issue-labeled.yml @armandgrillet
@@ -612,14 +614,15 @@ embed.go @grafana/grafana-as-code
 /.github/workflows/pr-commands.yml @marefr
 /.github/workflows/pr-patch-check.yml @grafana/grafana-delivery
 /.github/workflows/pr-patch-mirror-and-apply.yml @grafana/grafana-delivery
-/.github/workflows/publish-technical-documentation-next.yml @grafana/docs-grafana
+/.github/workflows/publish-technical-documentation-next.yml @grafana/docs-tooling
-/.github/workflows/publish-technical-documentation-release.yml @grafana/docs-grafana
+/.github/workflows/publish-technical-documentation-release.yml @grafana/docs-tooling
 /.github/workflows/remove-milestone.yml @grafana/grafana-delivery
 /.github/workflows/sbom-report.yml @grafana/security-team
 /.github/workflows/scripts/json-file-to-job-output.js @grafana/plugins-platform-frontend
 /.github/workflows/scripts/pr-get-job-link.js @grafana/plugins-platform-frontend
 /.github/workflows/stale.yml @grafana/grafana-delivery
 /.github/workflows/update-changelog.yml @grafana/grafana-delivery
+/.github/workflows/update-make-docs.yml @grafana/docs-tooling
 /.github/workflows/snyk.yml @grafana/security-team
 /.github/workflows/scripts/kinds/verify-kinds.go @grafana/grafana-as-code
 /.github/workflows/publish-kinds-next.yml @grafana/grafana-as-code

.github/workflows/doc-validator.yml

@@ -7,7 +7,7 @@ jobs:
   doc-validator:
     runs-on: "ubuntu-latest"
     container:
-      image: "grafana/doc-validator:v3.0.0"
+      image: "grafana/doc-validator:v3.2.0"
     steps:
       - name: "Checkout code"
         uses: "actions/checkout@v3"

.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 "bot@grafana.com"
+          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 }}

docs/make-docs

@@ -63,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'

docs/variables.mk

@@ -1,11 +1,11 @@
 # List of projects to provide to the make-docs script.
-PROJECTS = grafana
+PROJECTS := grafana
 
 # Use the doc-validator image defined in CI by default.
 export DOC_VALIDATOR_IMAGE := $(shell sed -En 's, *image: "(grafana/doc-validator[^"]+)",\1,p' "$(shell git rev-parse --show-toplevel)/.github/workflows/doc-validator.yml")
 
 # Skip some doc-validator checks.
-export DOC_VALIDATOR_SKIP_CHECKS := ^(?:image.+|canonical-does-not-match-pretty-URL)$
+export DOC_VALIDATOR_SKIP_CHECKS := $(shell sed -En "s, *'--skip-checks=(.+)',\1,p" "$(shell git rev-parse --show-toplevel)/.github/workflows/doc-validator.yml")
 
-# Use alternative image until make-docs 3.0.0 is rolled out.
+# Only run on sections that have been enabled in CI.
-export DOCS_IMAGE := grafana/docs-base:dbd975af06
+export DOC_VALIDATOR_INCLUDE := $(shell sed -En "s, *'--include=\\^docs/sources/(.+)',/hugo/content/docs/grafana/latest/\1,p" "$(shell git rev-parse --show-toplevel)/.github/workflows/doc-validator.yml")