tweak asciiDocs formatting to ease the mapping into the monitoring Docs

Hide the auto examples from asciiDocs as it's still WIP, to avoid confusion

Author: machine424

Documentation/resources.adoc

@@ -4,15 +4,9 @@
 // make edits or learn more about how this file is generated, read the docgen utility
 // instructions in the source code for the CMO.
 :_mod-docs-content-type: REFERENCE
-[id="resources-reference-for-the-cluster-monitoring-operator"]
+[id="resources-reference-for-the-cluster-monitoring-operator_{context}"]
 = Resources reference for the Cluster Monitoring Operator
-include::_attributes/common-attributes.adoc[]
-:context: resources-reference-for-the-cluster-monitoring-operator
 
-toc::[]
-
-[id="Cluster-monitoring-resources-reference"]
-== Cluster monitoring resources reference
 This document describes the following resources deployed and managed by the Cluster Monitoring Operator (CMO):
 
 * link:#cmo-routes-resources[Routes]
@@ -66,57 +60,23 @@ Expose the admission webhook service which validates `PrometheusRules` and `Aler
 === openshift-user-workload-monitoring/alertmanager-user-workload
 
 Expose the user-defined Alertmanager web server within the cluster on the following ports:
+
 * Port 9095 provides access to the Alertmanager endpoints. Granting access requires binding a user to the `monitoring-alertmanager-api-reader` role (for read-only operations) or `monitoring-alertmanager-api-writer` role in the `openshift-user-workload-monitoring` project.
 * Port 9092 provides access to the Alertmanager endpoints restricted to a given project. Granting access requires binding a user to the `monitoring-rules-edit` cluster role or `monitoring-edit` cluster role in the project.
 * Port 9097 provides access to the `/metrics` endpoint only. This port is for internal use, and no other usage is guaranteed.
 
 === openshift-monitoring/alertmanager-main
 
 Expose the Alertmanager web server within the cluster on the following ports:
-* Port 9094 provides access to all the Alertmanager endpoints. Granting access requires binding a user to the `monitoring-alertmanager-view` role (for read-only operations) or `monitoring-alertmanager-edit` role in the `openshift-monitoring` project.
-----
-# monitoring-alertmanager-view grants read permissions.
-$ oc project openshift-monitoring
-$ oc create serviceaccount am-ro-client
-$ oc adm policy add-role-to-user monitoring-alertmanager-view \
-  --role-namespace=openshift-monitoring --rolebinding-name=am-ro-client \
-  --serviceaccount=am-ro-client
-$ TOKEN=$(oc create token am-ro-client)
-$ ROUTE=$(oc get route alertmanager-main -n openshift-monitoring -ojsonpath={.spec.host})
-$ curl -H "Authorization: Bearer $TOKEN" -k --fail-with-body "https://$ROUTE/api/v2/alerts?filter=alertname=Watchdog"
-----
-----
-# monitoring-alertmanager-edit grants edit permissions.
-$ oc project openshift-monitoring
-$ oc create serviceaccount am-rw-client
-$ oc adm policy add-role-to-user monitoring-alertmanager-edit \
-  --role-namespace=openshift-monitoring --rolebinding-name=am-rw-client \
-  --serviceaccount=am-rw-client
-$ TOKEN=$(oc create token am-rw-client)
-$ ROUTE=$(oc get route alertmanager-main -n openshift-monitoring -ojsonpath={.spec.host})
-$ curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-  -d '{
-    "matchers": [
-      {
-        "name": "alertname",
-        "value": "MyTestAlert",
-        "isRegex": false
-      }
-    ],
-    "startsAt": "2044-01-01T00:00:00Z",
-    "endsAt": "2044-01-01T00:00:01Z",
-    "createdBy": "am-rw-client",
-    "comment": "Silence test"
-  }' \
-  -k --fail-with-body "https://$ROUTE/api/v2/silences"
-----
 
+* Port 9094 provides access to all the Alertmanager endpoints. Granting access requires binding a user to the `monitoring-alertmanager-view` role (for read-only operations) or `monitoring-alertmanager-edit` role in the `openshift-monitoring` project.
 * Port 9092 provides access to the Alertmanager endpoints restricted to a given project. Granting access requires binding a user to the `monitoring-rules-edit` cluster role or `monitoring-edit` cluster role in the project.
 * Port 9097 provides access to the `/metrics` endpoint only. This port is for internal use, and no other usage is guaranteed.
 
 === openshift-monitoring/kube-state-metrics
 
 Expose kube-state-metrics `/metrics` endpoints within the cluster on the following ports:
+
 * Port 8443 provides access to the Kubernetes resource metrics. This port is for internal use, and no other usage is guaranteed.
 * Port 9443 provides access to the internal kube-state-metrics metrics. This port is for internal use, and no other usage is guaranteed.
 
@@ -135,12 +95,14 @@ Expose the `/metrics` endpoint on port 9100. This port is for internal use, and
 === openshift-monitoring/openshift-state-metrics
 
 Expose openshift-state-metrics `/metrics` endpoints within the cluster on the following ports:
+
 * Port 8443 provides access to the OpenShift resource metrics. This port is for internal use, and no other usage is guaranteed.
 * Port 9443 provides access to the internal `openshift-state-metrics` metrics. This port is for internal use, and no other usage is guaranteed.
 
 === openshift-monitoring/prometheus-k8s
 
 Expose the Prometheus web server within the cluster on the following ports:
+
 * Port 9091 provides access to all the Prometheus endpoints. Granting access requires binding a user to the `cluster-monitoring-view` cluster role.
 * Port 9092 provides access to the `/metrics` and `/federate` endpoints only. This port is for internal use, and no other usage is guaranteed.
 
@@ -155,6 +117,7 @@ Expose the `/metrics` endpoint on port 8443. This port is for internal use, and
 === openshift-user-workload-monitoring/prometheus-user-workload
 
 Expose the Prometheus web server within the cluster on the following ports:
+
 * Port 9091 provides access to the `/metrics` endpoint only. This port is for internal use, and no other usage is guaranteed.
 * Port 9092 provides access to the `/federate` endpoint only. Granting access requires binding a user to the `cluster-monitoring-view` cluster role.
 
@@ -167,6 +130,7 @@ Expose the `/metrics` endpoint on port 8443. This port is for internal use, and
 === openshift-monitoring/thanos-querier
 
 Expose the Thanos Querier web server within the cluster on the following ports:
+
 * Port 9091 provides access to all the Thanos Querier endpoints. Granting access requires binding a user to the `cluster-monitoring-view` cluster role.
 * Port 9092 provides access to the `/api/v1/query`, `/api/v1/query_range/`, `/api/v1/labels`, `/api/v1/label/*/values`, and `/api/v1/series` endpoints restricted to a given project. Granting access requires binding a user to the `view` cluster role in the project.
 * Port 9093 provides access to the `/api/v1/alerts`, and `/api/v1/rules` endpoints restricted to a given project. Granting access requires binding a user to the `monitoring-rules-edit` cluster role or `monitoring-edit` cluster role or `monitoring-rules-view` cluster role in the project.
@@ -175,6 +139,7 @@ Expose the Thanos Querier web server within the cluster on the following ports:
 === openshift-user-workload-monitoring/thanos-ruler
 
 Expose the Thanos Ruler web server within the cluster on the following ports:
+
 * Port 9091 provides access to all Thanos Ruler endpoints. Granting access requires binding a user to the `cluster-monitoring-view` cluster role.
 * Port 9092 provides access to the `/metrics` endpoint only. This port is for internal use, and no other usage is guaranteed.
 

hack/docgen/managed_resources.go

@@ -59,15 +59,9 @@ To avoid these issues, follow these recommendations:
 // make edits or learn more about how this file is generated, read the docgen utility
 // instructions in the source code for the CMO.
 :_mod-docs-content-type: REFERENCE
-[id="resources-reference-for-the-cluster-monitoring-operator"]
+[id="resources-reference-for-the-cluster-monitoring-operator_{context}"]
 = Resources reference for the Cluster Monitoring Operator
-include::_attributes/common-attributes.adoc[]
-:context: resources-reference-for-the-cluster-monitoring-operator
 
-toc::[]
-
-[id="Cluster-monitoring-resources-reference"]
-== Cluster monitoring resources reference
 This document describes the following resources deployed and managed by the Cluster Monitoring Operator (CMO):
 
 * link:#cmo-routes-resources[Routes]
@@ -168,6 +162,11 @@ func PrintManagedResources(format string) error {
 			return err
 		}
 
+		desc, err = formatDescription(desc, format)
+		if err != nil {
+			return err
+		}
+
 		resourcesByKind[o.GetKind()] = append(
 			resourcesByKind[o.GetKind()],
 			resource{
@@ -249,7 +248,34 @@ func substitutePlaceholdersInDescription(desc, format string) (string, error) {
 		} else {
 			content = suite.StringMarkdown()
 		}
-		lines = append(lines, content)
+		// TODO: remove once unnecessary
+		if content != "" {
+			lines = append(lines, content)
+		}
+	}
+	if err := scanner.Err(); err != nil {
+		return "", err
+	}
+	return strings.Join(lines, "\n"), nil
+}
+
+// formatDescription improves the formatting of the description according to the desired format.
+// For example, for better list rendering.
+func formatDescription(desc, format string) (string, error) {
+	if format != asciiDocsFormat {
+		return desc, nil
+	}
+
+	var lines []string
+	scanner := bufio.NewScanner(strings.NewReader(desc))
+	for scanner.Scan() {
+		line := scanner.Text()
+		lines = append(lines, line)
+		// Supposing a list will exist after "foo bar:"
+		// make sure to add a new line for better rendering.
+		if strings.HasSuffix(line, ":") {
+			lines = append(lines, "")
+		}
 	}
 	if err := scanner.Err(); err != nil {
 		return "", err

test/e2e/test_command/test_command.go

@@ -105,7 +105,9 @@ func (suite *Suite) StringMarkdown() string {
 }
 
 func (suite *Suite) StringAscii() string {
-	return suite.intoCodeBlocks("----")
+	// Not ready to be part of the doc yet.
+	return ""
+	// return suite.intoCodeBlocks("----")
 }
 
 func (stc *SetUpTearDownCommand) Run(t *testing.T, wDir, kubeConfigPath string) error {