docs: move build instructions from Antora into Markdown (#173)

* docs: move build instructions from Antora into Markdown

* fix admonition

* fix admonition

* Reference build instructions in README

Author: fhennig

.readme/partials/main.md.j2

@@ -8,6 +8,10 @@ A CSI provider intended to provide an abstract way to expose a single Pod to the
 
 You can install the operator using [stackablectl or helm](https://docs.stackable.tech/home/stable/{{operator_docs_slug}}/getting_started/installation).
 
+## Building
+
+As a user you do not need to build the operator yourself, but for development purposes you can read the [build instructions](./BUILDING.md) to learn how to build the operator.
+
 {% filter trim %}
   {%- include "partials/borrowed/documentation.md.j2" -%}
 {% endfilter %}

docs/modules/listener-operator/pages/building.adoc renamed to BUILDING.md

@@ -1,24 +1,23 @@
-= Building the Operator
+# Building the operator
 
 This operator is written in Rust.
 
 It is developed against the latest stable Rust release, and we currently don't support any older versions.
 
-The Listener Operator is a https://github.com/container-storage-interface/spec/blob/master/spec.md[Container Storage Interface (CSI)] provider plugin
-for the local Kubelet, which means that it should only be executed inside a Kubernetes `Pod`. Currently, the following ways are supported to build the Listener Operator:
+The Listener operator is a [Container Storage Interface (CSI)](https://github.com/container-storage-interface/spec/blob/master/spec.md) provider plugin
+for the local Kubelet, which means that it should only be executed inside a Kubernetes Pod. Currently, the following ways are supported to build the Listener operator:
 
 * `docker build`
-* https://nixos.org/[Nix]
+* [Nix](https://nixos.org/)
 
 The `docker build` command is currently the primary deployment target, and the official images are built
 using it. However, Nix has much faster incremental build and deployment times, making it ideal for local development.
 
-== Docker
+## Docker
 
 To build and deploy to the active Kind cluster, run:
 
-[source,console]
-----
+```shell
 $ echo Building with Docker
 # Ensure that all submodules are up-to-date
 $ git submodule update --recursive --init
@@ -33,16 +32,15 @@ $ kind load docker-image "$REPO:$TAG"
 $ docker run --rm "$REPO:$TAG" crd | kubectl apply -f-
 # Deploy
 $ helm upgrade listener-operator deploy/helm/listener-operator \
-       --install \
-       --set-string "image.repository=$REPO,image.tag=$TAG"
-----
+    --install \
+    --set-string "image.repository=$REPO,image.tag=$TAG"
+```
 
-== Nix
+## Nix
 
 To build and deploy to the active Kind cluster, run the following Bash commands:
 
-[source,console]
-----
+```shell
 $ echo Building with Nix
 # Ensure that all submodules are up-to-date
 $ git submodule update --recursive --init
@@ -67,29 +65,28 @@ $ kubectl apply -f result/crds.yaml
 $ helm upgrade listener-operator deploy/helm/listener-operator \
   --install \
   --set-string "image.repository=$(cat result/image-repo),image.tag=$(cat result/image-tag)"
-----
+```
 
 You may need to add `extra-experimental-features = nix-command` to `/etc/nix/nix.conf`, or add `--experimental-features nix-command` to the Nix commands.
 
-You can also use https://tilt.dev/[Tilt] to automatically rebuild and redeploy when files are changed:
+You can also use [Tilt](https://tilt.dev/) to automatically rebuild and redeploy when files are changed:
 
-[source,console]
-----
+```shell
 $ nix run -f . tilt up
-----
+```
 
-== K3d
+## K3d
 
-The Listener Operator, as with most CSI providers, requires the Kubernetes node's root folder to be mounted as `rshared`. K3d does not do this by default,
+The Listener operator, as with most CSI providers, requires the Kubernetes node's root folder to be mounted as `rshared`. K3d does not do this by default,
 but can be prodded into doing this by running `mount --make-rshared /` in each node container.
 
 To do this for each running K3d node, run the following script:
 
-[source,console]
-----
+```shell
 for i in $(k3d node list -o json | jq -r .[].name); do
   docker exec -it $i mount --make-rshared /
 done
-----
+```
 
-NOTE: This is _not_ persistent, and must be re-executed every time the cluster (or a node in it) is restarted.
+> [!IMPORTANT]
+> This is _not_ persistent, and must be re-executed every time the cluster (or a node in it) is restarted.

README.md

@@ -18,6 +18,10 @@ It is part of the Stackable Data Platform, a curated selection of the best open
 
 You can install the operator using [stackablectl or helm](https://docs.stackable.tech/home/stable/listener-operator/getting_started/installation).
 
+## Building
+
+As a user you do not need to build the operator yourself, but for development purposes you can read the [build instructions](./BUILDING.md) to learn how to build the operator.
+
 ## Documentation
 
 The stable documentation for this operator can be found [here](https://docs.stackable.tech/home/stable/listener-operator).

docs/modules/listener-operator/partials/nav.adoc

@@ -1,4 +1,3 @@
-* xref:listener-operator:building.adoc[]
 * xref:listener-operator:installation.adoc[]
 * xref:listener-operator:usage.adoc[]
 * Concepts