Add tests to verify links in documentation (#551)

Author: thegridman

.github/workflows/build.yaml

@@ -118,6 +118,10 @@ jobs:
       shell: bash
       run: make test-all
 
+    - name: Doc Tests
+      shell: bash
+      run: make test-docs
+
     - name: E2E Local Tests
       shell: bash
       run: make e2e-local-test

Makefile

@@ -591,9 +591,9 @@ api/v1/zz_generated.deepcopy.go: $(API_GO_FILES) controller-gen
 .PHONY: api-doc-gen
 api-doc-gen: docs/about/04_coherence_spec.adoc  ## Generate API documentation
 
-docs/about/04_coherence_spec.adoc: $(API_GO_FILES)
+docs/about/04_coherence_spec.adoc: $(API_GO_FILES) utils/docgen/main.go
 	@echo "Generating CRD Doc"
-	go run ./docgen/ \
+	go run ./utils/docgen/ \
 		api/v1/coherenceresourcespec_types.go \
 		api/v1/coherence_types.go \
 		api/v1/coherenceresource_types.go \
@@ -1981,7 +1981,7 @@ version:
 # Build the documentation.
 # ----------------------------------------------------------------------------------------------------------------------
 .PHONY: docs
-docs:
+docs: api-doc-gen
 	./mvnw -B -f java install -P docs -pl docs -DskipTests \
 		-Doperator.version=$(VERSION) \
 		-Doperator.image=$(OPERATOR_IMAGE) \
@@ -1991,6 +1991,21 @@ docs:
 	cp -R docs/images/* build/_output/docs/images/
 	find examples/ -name \*.png -exec cp {} build/_output/docs/images/images/ \;
 
+# ----------------------------------------------------------------------------------------------------------------------
+# Test the documentation.
+# ----------------------------------------------------------------------------------------------------------------------
+.PHONY: test-docs
+test-docs: docs
+	go run ./utils/linkcheck/ --file $(BUILD_OUTPUT)/docs/pages/... \
+		--exclude 'https://oracle.github.io/coherence-operator/charts' \
+		--exclude 'https://github.com/oracle/coherence-operator/releases' \
+		--exclude 'https://oracle.github.io/coherence-operator/docs/latest/' \
+		--exclude 'http://proxyserver' \
+		--exclude 'http://<pod-ip' \
+		--exclude 'http://elasticsearch-master' \
+		--exclude 'http://payments' \
+ 		2>&1 | tee $(TEST_LOGS_DIR)/doc-link-check.log
+
 # ----------------------------------------------------------------------------------------------------------------------
 # Start a local web server to serve the documentation.
 # ----------------------------------------------------------------------------------------------------------------------

api/v1/coherence_types.go

@@ -1162,83 +1162,83 @@ type ServiceMonitorSpec struct {
 	// +optional
 	Labels map[string]string `json:"labels,omitempty"`
 	// The label to use to retrieve the job name from.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#servicemonitorspec
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#servicemonitorspec
 	// +optional
 	JobLabel string `json:"jobLabel,omitempty"`
 	// TargetLabels transfers labels on the Kubernetes Service onto the target.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#servicemonitorspec
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#servicemonitorspec
 	// +listType=atomic
 	// +optional
 	TargetLabels []string `json:"targetLabels,omitempty"`
 	// PodTargetLabels transfers labels on the Kubernetes Pod onto the target.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#servicemonitorspec
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#servicemonitorspec
 	// +listType=atomic
 	// +optional
 	PodTargetLabels []string `json:"podTargetLabels,omitempty"`
 	// SampleLimit defines per-scrape limit on number of scraped samples that will be accepted.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#servicemonitorspec
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#servicemonitorspec
 	// +optional
 	SampleLimit uint64 `json:"sampleLimit,omitempty"`
 	// HTTP path to scrape for metrics.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	Path string `json:"path,omitempty"`
 	// HTTP scheme to use for scraping.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	Scheme string `json:"scheme,omitempty"`
 	// Optional HTTP URL parameters
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	Params map[string][]string `json:"params,omitempty"`
 	// Interval at which metrics should be scraped
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	Interval monitoringv1.Duration `json:"interval,omitempty"`
 	// Timeout after which the scrape is ended
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	ScrapeTimeout monitoringv1.Duration `json:"scrapeTimeout,omitempty"`
 	// TLS configuration to use when scraping the endpoint
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	TLSConfig *monitoringv1.TLSConfig `json:"tlsConfig,omitempty"`
 	// File to read bearer token for scraping targets.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	BearerTokenFile string `json:"bearerTokenFile,omitempty"`
 	// Secret to mount to read bearer token for scraping targets. The secret
 	// needs to be in the same namespace as the service monitor and accessible by
 	// the Prometheus Operator.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	BearerTokenSecret corev1.SecretKeySelector `json:"bearerTokenSecret,omitempty"`
 	// HonorLabels chooses the metric labels on collisions with target labels.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	HonorLabels bool `json:"honorLabels,omitempty"`
 	// HonorTimestamps controls whether Prometheus respects the timestamps present in scraped data.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	HonorTimestamps *bool `json:"honorTimestamps,omitempty"`
 	// BasicAuth allow an endpoint to authenticate over basic authentication
 	// More info: https://prometheus.io/docs/operating/configuration/#endpoints
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	BasicAuth *monitoringv1.BasicAuth `json:"basicAuth,omitempty"`
 	// MetricRelabelings to apply to samples before ingestion.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +listType=atomic
 	// +optional
 	MetricRelabelings []*monitoringv1.RelabelConfig `json:"metricRelabelings,omitempty"`
 	// Relabelings to apply to samples before scraping.
 	// More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +listType=atomic
 	// +optional
 	Relabelings []*monitoringv1.RelabelConfig `json:"relabelings,omitempty"`
 	// ProxyURL eg http://proxyserver:2195 Directs scrapes to proxy through this endpoint.
-	// See https://coreos.com/operators/prometheus/docs/latest/api.html#endpoint
+	// See https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#endpoint
 	// +optional
 	ProxyURL *string `json:"proxyURL,omitempty"`
 }
@@ -1805,7 +1805,6 @@ type ServiceSpec struct {
 	// If specified and supported by the platform, this will restrict traffic through the cloud-provider
 	// load-balancer will be restricted to the specified client IPs. This field will be ignored if the
 	// cloud-provider does not support the feature."
-	// More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/
 	// +listType=atomic
 	// +optional
 	LoadBalancerSourceRanges []string `json:"loadBalancerSourceRanges,omitempty"`