Refactor Asciidoc documentation and remove Markdown

CONTRIBUTING.md

@@ -70,7 +70,56 @@ When your pull request is in, it will automatically have a battery of automatic
 
 ## Testing
 
-The testing philosophy of this project is described in [README.md](/README.md#testing) - it is somewhat unconventional, since the project is not a single piece of code but rather an amalgamation of various other tools all plumbed together.
+The testing philosophy of this project is described below - it is somewhat unconventional, since the project is not a single piece of code but rather an amalgamation of various other tools all plumbed together.
+
+We need to verify the following key use cases:
+
+* Out of the box defaults provided for simple usage to give a cluster overview
+* Customization of rules and integrate into existing pipeline
+
+In two separate infrastructures:
+
+* Deploying microlith to Kubernetes using CAO, automatic service discovery
+ ** Without CAO still possible but not tested
+ ** Can also mix-and-match this with on-premise cluster (COS in k8s, Couchbase Server on premise)
+* Deploying on-premise using manual configuration with the microlith
+ ** Remote end point or in Vagrant as well
+
+We need to test the following aspects:
+
+* Prometheus endpoint is available from the microlith
+* Adding the Couchbase Server instances to be monitored
+* Couchbase Server metrics are available (using the exporter pre 7.0) from the microlith endpoint
+ ** PromQL or promcli tooling can verify this
+* Default alerting rules are triggered under appropriate failures
+ ** Defaults in general just work out of the box
+* Custom alerting rules can be provided
+ ** Extend existing
+ ** Replace defaults
+ ** Disable defaults
+* Grafana dashboards are available from the microlith
+* Custom dashboards can be provided to the microlith
+ ** We can query the REST API for this information, i.e. what rules are present and firing, etc.
+* Loki endpoint is available from the microlith
+ ** LogQL can verify this and that there is some data (need to ensure we send some logs)
+* Components within the microlith can be enabled or disabled
+ ** Repeat one of the previous tests (e.g. Loki) with the component disabled and confirm the test fails.
+* Reproducible ephemeral container with custom configuration via GitOps
+ ** Configuration of cluster connection & credentials
+ ** Addition of custom alerts and tuning/inhibition of those alerts, plus addition of custom dashboards
+* Integration with an existing stack
+ ** Use Grafana operator here to create a separate stack in another namespace and demonstrate we can use this.
+
+Variation points:
+
+* Clusters with and without Prometheus end points
+* Clusters using CBS 7.0+ and Prometheus exporter
+* Clusters with different credentials
+* Clusters using different versions of Couchbase Server
+* In same namespace and separate namespaces
+* With and without the useful extras like kube-state-metrics and eventrouter
+* CE and EE clusters (not with CAO though for EE)
+* On-prem and CAO clusters mixed together for monitoring
 
 Our tests are implemented in Bash using the [BATS framework](https://bats-core.readthedocs.io/en/stable/).
 

Makefile

@@ -15,7 +15,7 @@ GIT_REVISION := $(shell git rev-parse HEAD)
 # This is analogous to revisions in DEB and RPM archives.
 revision = $(if $(REVISION),$(REVISION),)
 
-.PHONY: all build lint container container-oss config-svc-container container-public container-lint container-scan dist test-dist container-clean clean examples example-containers test test-kubernetes test-native test-containers docs docs-generate-markdown docs-lint docs-license-analysis
+.PHONY: all build lint container container-oss config-svc-container container-public container-lint container-scan dist test-dist container-clean clean examples example-containers test test-kubernetes test-native test-containers docs docs-lint docs-license-analysis
 
 # TODO: add 'test examples'
 all: clean build lint container container-oss container-lint container-scan dist test-dist
@@ -135,18 +135,7 @@ docs-lint:
 	docker run --rm -i hadolint/hadolint < Dockerfile.docs
 	tools/asciidoc-lint.sh
 
-docs: docs-generate-markdown
-
-# Automatically convert Markdown docs to Asciidoc ones.
-# This command needs bind mount support so will not run in Couchbase build infrastructure (Docker Swarm):
-# docker run -u $(shell id -u) -v $$PWD:/documents asciidoctor/docker-asciidoctor kramdoc README.md -o docs/modules/ROOT/pages/index.adoc
-# We therefore create a custom container for it all. Unfortunately this has a knock on in that forwarding can mess up line endings.
-docs-generate-markdown:
-	DOCKER_BUILDKIT=1 docker build -t ${DOCKER_USER}/observability-stack-docs-generator:${DOCKER_TAG} -f Dockerfile.docs .
-	docker run --rm -t ${DOCKER_USER}/observability-stack-docs-generator:${DOCKER_TAG} > docs/modules/ROOT/pages/index.adoc
-	tr -d "\r" < docs/modules/ROOT/pages/index.adoc > /tmp/observability-stack-docs-output.adoc
-	mv /tmp/observability-stack-docs-output.adoc docs/modules/ROOT/pages/index.adoc
-	rm -f observability-stack-docs-output.adoc
+docs:
 
 docs-license-analysis:
 	tools/tern-report.sh