From 9658607c42c88ea0b9fc13688a74a6a304eca236 Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 14 Jul 2023 14:42:12 +0100 Subject: [PATCH] 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 * Add workflow to automatically update `make docs` procedure daily Signed-off-by: Jack Baldry * Update `make docs` procedure Signed-off-by: Jack Baldry --------- Signed-off-by: Jack Baldry --- .github/workflows/update-make-docs.yml | 27 ++++++++++++ CODEOWNERS | 8 ++++ docs/docs.mk | 7 +-- docs/make-docs | 61 +++++++++++++++++++------- docs/variables.mk | 7 ++- 5 files changed, 86 insertions(+), 24 deletions(-) create mode 100644 .github/workflows/update-make-docs.yml diff --git a/.github/workflows/update-make-docs.yml b/.github/workflows/update-make-docs.yml new file mode 100644 index 000000000000..57d60d47c114 --- /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/CODEOWNERS b/CODEOWNERS index 3342ba4ccab9..91eb18999c55 100644 --- 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 index 53f4256a9b6d..4c729c57d7c7 100644 --- 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 index 3b8c505b5058..4bb5ad79038a 100755 --- 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 <&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 < "\${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 index 464ebfb7a06f..82dba27a62d8 100644 --- 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)))