From e8b4228f8994667885936562eda1c2dac821728e Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Thu, 13 Jul 2023 18:24:23 +0100 Subject: [PATCH] Update `make docs` procedure and related workflows (#71537) * Add myself as CODEOWNER for `make docs` procedure and related workflows Signed-off-by: Jack Baldry * Update `make docs` procedure Signed-off-by: Jack Baldry * Add workflow to update `make docs` procedure Signed-off-by: Jack Baldry * Update doc-validator workflow Signed-off-by: Jack Baldry * Fix team handle Signed-off-by: Jack Baldry * Clean up CODEOWNERS Signed-off-by: Jack Baldry --------- Signed-off-by: Jack Baldry --- .github/CODEOWNERS | 43 ++++++++++++++------------ .github/workflows/doc-validator.yml | 2 +- .github/workflows/update-make-docs.yml | 27 ++++++++++++++++ docs/make-docs | 7 +++-- docs/variables.mk | 8 ++--- 5 files changed, 60 insertions(+), 27 deletions(-) create mode 100644 .github/workflows/update-make-docs.yml diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index aeb3b1e2595..709097af7a4 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -33,23 +33,25 @@ /devenv/README.md @grafana/docs-grafana # Technical documentation -/docs/ @Eve832 @jdbaldry -/docs/sources/ @Eve832 -/docs/sources/administration/ @Eve832 @GrafanaWriter -/docs/sources/alerting/ @brendamuir -/docs/sources/dashboards/ @imatwawana -/docs/sources/datasources/ @lwandz13 -/docs/sources/explore/ @Eve832 @GrafanaWriter -/docs/sources/fundamentals @chri2547 -/docs/sources/getting-started/ @chri2547 -/docs/sources/introduction/ @chri2547 -/docs/sources/old-alerting/ @brendamuir -/docs/sources/panels-visualizations/ @imatwawana -/docs/sources/release-notes/ @Eve832 @GrafanaWriter -/docs/sources/setup-grafana/ @chri2547 -/docs/sources/upgrade-guide/ @chri2547 @imatwawana -/docs/sources/whatsnew/ @chri2547 @imatwawana -/docs/sources/developers/plugins/ @Eve832 @josmperez @grafana/plugins-platform-frontend @grafana/plugins-platform-backend +# `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 +/docs/sources/dashboards/ @imatwawana +/docs/sources/datasources/ @lwandz13 +/docs/sources/explore/ @Eve832 @GrafanaWriter +/docs/sources/fundamentals @chri2547 +/docs/sources/getting-started/ @chri2547 +/docs/sources/introduction/ @chri2547 +/docs/sources/old-alerting/ @brendamuir +/docs/sources/panels-visualizations/ @imatwawana +/docs/sources/release-notes/ @Eve832 @GrafanaWriter +/docs/sources/setup-grafana/ @chri2547 +/docs/sources/upgrade-guide/ @chri2547 @imatwawana +/docs/sources/whatsnew/ @chri2547 @imatwawana +/docs/sources/developers/plugins/ @Eve832 @josmperez @grafana/plugins-platform-frontend @grafana/plugins-platform-backend /docs/sources/developers/plugins/introduction-to-plugin-development/backend/ @Eve832 @grafana/plugins-platform-backend # Backend code @@ -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-release.yml @grafana/docs-grafana +/.github/workflows/publish-technical-documentation-next.yml @grafana/docs-tooling +/.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 diff --git a/.github/workflows/doc-validator.yml b/.github/workflows/doc-validator.yml index 792506ff46d..88a731676fc 100644 --- a/.github/workflows/doc-validator.yml +++ b/.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" diff --git a/.github/workflows/update-make-docs.yml b/.github/workflows/update-make-docs.yml new file mode 100644 index 00000000000..57d60d47c11 --- /dev/null +++ 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 "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 }} diff --git a/docs/make-docs b/docs/make-docs index 3942bf483c3..4bb5ad79038 100755 --- a/docs/make-docs +++ b/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' diff --git a/docs/variables.mk b/docs/variables.mk index 2dfa301900c..a3302041ce5 100644 --- a/docs/variables.mk +++ b/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. -export DOCS_IMAGE := grafana/docs-base:dbd975af06 +# Only run on sections that have been enabled in CI. +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")