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

@@ -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'] },
     ],

.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
 
 ...

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.

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 #
 ###################

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: <list of strings> | default = [en0]]
+[instance_interface_names: <list of strings> | default = [<private network interfaces>]]
 
 # Compress HTTP responses.
 # CLI flag: -querier.compress-http-responses

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=[<private network interfaces>]"`
 
 	// If set, address is not computed from interfaces.
 	Addr string `yaml:"address" doc:"hidden"`