From 86d33a4e4a87eaeb0d9016bdff10ff7259525968 Mon Sep 17 00:00:00 2001 From: Susana Ferreira Date: Wed, 14 Dec 2022 17:46:16 +0100 Subject: [PATCH] Add CI step to check generated documentation to check pipeline (#7938) **What this PR does / why we need it**: Follow up from PR: https://github.com/grafana/loki/pull/7916 to add a CI step to check if the configuration flag documentation file `doc/sources/configuration/_index.md` was generated successfully. Requirements: * CI `check` pipeline should fail if the documentation file is updated manually * CI `check` pipeline should fail if registration flags are changed in the code, but the documentation file is not generated. **Which issue(s) this PR fixes**: Fixes https://github.com/grafana/loki-private/issues/83 **Special notes for your reviewer**: **Checklist** - [ ] Reviewed the `CONTRIBUTING.md` guide - [ ] Documentation added - [ ] Tests updated - [x] `CHANGELOG.md` updated - [ ] Changes that require user attention or interaction to upgrade are documented in `docs/sources/upgrading/_index.md` --- .drone/drone.jsonnet | 1 + .drone/drone.yml | 9 ++++++++- CHANGELOG.md | 5 +++++ Makefile | 18 ++++++++++++++++++ docs/sources/configuration/_index.md | 2 +- pkg/lokifrontend/frontend/v2/frontend.go | 2 +- 6 files changed, 34 insertions(+), 3 deletions(-) diff --git a/.drone/drone.jsonnet b/.drone/drone.jsonnet index 41fc42c08b..c69f206f1b 100644 --- a/.drone/drone.jsonnet +++ b/.drone/drone.jsonnet @@ -548,6 +548,7 @@ local manifest_ecr(apps, archs) = pipeline('manifest-ecr') { commands: ['apk add make bash && make lint-scripts'], }, make('loki', container=false) { depends_on: ['check-generated-files'] }, + make('check-doc', container=false) { depends_on: ['loki'] }, make('validate-example-configs', container=false) { depends_on: ['loki'] }, make('check-example-config-doc', container=false) { depends_on: ['clone'] }, ], diff --git a/.drone/drone.yml b/.drone/drone.yml index f86de6af6c..03f098aad9 100644 --- a/.drone/drone.yml +++ b/.drone/drone.yml @@ -189,6 +189,13 @@ steps: environment: {} image: grafana/loki-build-image:0.25.0 name: loki +- commands: + - make BUILD_IN_CONTAINER=false check-doc + depends_on: + - loki + environment: {} + image: grafana/loki-build-image:0.25.0 + name: check-doc - commands: - make BUILD_IN_CONTAINER=false validate-example-configs depends_on: @@ -1613,6 +1620,6 @@ kind: secret name: gpg_private_key --- kind: signature -hmac: a993b5d815323a831ad4b7f3264e7d6726774cdf4a041f4818af50f366101079 +hmac: 12435dae603e73b3afd6cf014e723b8ff84c04d4476917c72d5f9b81251d43ad ... diff --git a/CHANGELOG.md b/CHANGELOG.md index d8f61fe612..1f03bd2275 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ * [7785](https://github.com/grafana/loki/pull/7785) **dannykopping**: Add query blocker for queries and rules. * [7804](https://github.com/grafana/loki/pull/7804) **sandeepsukhani**: Use grpc for communicating with compactor for query time filtering of data requested for deletion. * [7817](https://github.com/grafana/loki/pull/7817) **kavirajk**: fix(memcached): panic on send on closed channel. +* [7916](https://github.com/grafana/loki/pull/7916) **ssncferreira**: Add `doc-generator` tool to generate configuration flags documentation. ##### Fixes @@ -50,6 +51,10 @@ #### Jsonnet +#### Build + +* [7938](https://github.com/grafana/loki/pull/7938) **ssncferreira**: Add DroneCI pipeline step to validate configuration flags documentation generation. + ### Notes This release was created from a branch starting at commit FIXME but it may also contain backported changes from main. diff --git a/Makefile b/Makefile index 3343bf74c4..b816d73cd8 100644 --- a/Makefile +++ b/Makefile @@ -7,6 +7,7 @@ .PHONY: bigtable-backup, push-bigtable-backup .PHONY: benchmark-store, drone, check-drone-drift, check-mod .PHONY: migrate migrate-image lint-markdown ragel +.PHONY: doc check-doc .PHONY: validate-example-configs generate-example-config-doc check-example-config-doc .PHONY: clean clean-protos @@ -71,6 +72,13 @@ RAGEL_GOS := $(patsubst %.rl,%.rl.go,$(RAGEL_DEFS)) PROMTAIL_GENERATED_FILE := clients/pkg/promtail/server/ui/assets_vfsdata.go PROMTAIL_UI_FILES := $(shell find ./clients/pkg/promtail/server/ui -type f -name assets_vfsdata.go -prune -o -print) +# Documentation source path +DOC_SOURCES_PATH := docs/sources + +# Configuration flags documentation +DOC_FLAGS_TEMPLATE := $(DOC_SOURCES_PATH)/configuration/index.template +DOC_FLAGS := $(DOC_SOURCES_PATH)/configuration/_index.md + ########## # Docker # ########## @@ -719,6 +727,16 @@ format: find . $(DONT_FIND) -name '*.pb.go' -prune -o -name '*.y.go' -prune -o -name '*.rl.go' -prune -o \ -type f -name '*.go' -exec goimports -w -local github.com/grafana/loki {} \; +# Documentation related commands + +doc: ## Generates the config file documentation + go run ./tools/doc-generator $(DOC_FLAGS_TEMPLATE) > $(DOC_FLAGS) + +check-doc: ## Check the documentation files are up to date +check-doc: doc + @find . -name "*.md" | xargs git diff --exit-code -- \ + || (echo "Please update generated documentation by running 'make doc' and committing the changes" && false) + ################### # Example Configs # ################### diff --git a/docs/sources/configuration/_index.md b/docs/sources/configuration/_index.md index 15dd42aa29..d51e347de5 100644 --- a/docs/sources/configuration/_index.md +++ b/docs/sources/configuration/_index.md @@ -670,7 +670,7 @@ The `frontend` block configures the Loki query-frontend. # query-scheduler and querier, which uses it to send the query response back to # query-frontend. # CLI flag: -frontend.instance-interface-names -[instance_interface_names: | default = [en0]] +[instance_interface_names: | default = []] # Compress HTTP responses. # CLI flag: -querier.compress-http-responses diff --git a/pkg/lokifrontend/frontend/v2/frontend.go b/pkg/lokifrontend/frontend/v2/frontend.go index f0f622bd25..cf4d49cc31 100644 --- a/pkg/lokifrontend/frontend/v2/frontend.go +++ b/pkg/lokifrontend/frontend/v2/frontend.go @@ -39,7 +39,7 @@ type Config struct { GRPCClientConfig grpcclient.Config `yaml:"grpc_client_config"` // Used to find local IP address, that is sent to scheduler and querier-worker. - InfNames []string `yaml:"instance_interface_names"` + InfNames []string `yaml:"instance_interface_names" doc:"default=[]"` // If set, address is not computed from interfaces. Addr string `yaml:"address" doc:"hidden"`