operator generate reference based on Go Structs

.github/workflows/general.yaml

@@ -29,6 +29,7 @@ jobs:
       - name: "Build Documentation Test"
         run: |
           ./doc-builder update-repositories
+          ./doc-builder gen-operator-ref
           ./doc-builder build
   dev-deployment:
     runs-on: ubuntu-latest
@@ -46,6 +47,7 @@ jobs:
           sed -i -r "s|(site_url: .*)|\1dev/|g" ./mkdocs.yml
           cat ./mkdocs.yml
           ./doc-builder update-repositories
+          ./doc-builder gen-operator-ref
           ./doc-builder build
       - name: "Creating Deployment Artifact"
         run: |

.github/workflows/pull_request.yaml

@@ -39,6 +39,7 @@ jobs:
       - name: "Build Documentation Test"
         run: |
           ./doc-builder update-repositories
+          ./doc-builder gen-operator-ref
           ./doc-builder build
   build-deploy-pr:
     if: github.event.action != 'closed'
@@ -53,6 +54,7 @@ jobs:
       - name: "Build Documentation"
         run: |
           ./doc-builder update-repositories
+          ./doc-builder gen-operator-ref
           ./doc-builder build
       - name: "Creating Deployment Artifact"
         run: |

.github/workflows/release.yaml

@@ -37,9 +37,13 @@ jobs:
       - name: "Lock sbcli/sbcli version"
         run: |
           [ -f ./scripts/sbcli.lock ] || echo "${{ env.RELEASE_NAME }}" > ./scripts/sbcli.lock
+      - name: "Lock simplyblock-operator version"
+        run: |
+          ./scripts/operator-lock.sh "${{ env.RELEASE_NAME }}"
       - name: "Prepare Documentation Deployment: ${{ env.RELEASE_NAME }}"
         run: |
           ./doc-builder update-repositories
+          ./doc-builder gen-operator-ref
           ./doc-builder deploy ${{ env.RELEASE_NAME }}
       - name: "Create Version Tag: ${{ env.RELEASE_NAME }}"
         run: |
@@ -48,9 +52,11 @@ jobs:
           git config user.email github-actions@github.com
           git add deployment
           git add scripts/sbcli.lock
+          if [ -f scripts/operator.lock ]; then git add scripts/operator.lock; fi
           git commit -m "Auto-Build: ${RELEASE_NAME}"
           git tag ${RELEASE_NAME}
           git rm scripts/sbcli.lock
+          if [ -f scripts/operator.lock ]; then git rm scripts/operator.lock; fi
           git commit -m "Auto-Build: Post ${RELEASE_NAME}"
           git push --all
           git push --tags

.github/workflows/update-release.yaml

@@ -40,9 +40,13 @@ jobs:
       - name: "Lock sbcli/sbcli version"
         run: |
           [ -f ./scripts/sbcli.lock ] || echo "${{ env.RELEASE_NAME }}" > ./scripts/sbcli.lock
+      - name: "Lock simplyblock-operator version"
+        run: |
+          ./scripts/operator-lock.sh "${{ env.RELEASE_NAME }}"
       - name: "Prepare Documentation Deployment: ${{ env.RELEASE_NAME }}"
         run: |
           ./doc-builder update-repositories
+          ./doc-builder gen-operator-ref
           ./doc-builder deploy ${{ env.RELEASE_NAME }} --force
       - name: "Create Version Tag: ${{ env.RELEASE_NAME }}"
         run: |
@@ -53,9 +57,11 @@ jobs:
           git tag -d ${RELEASE_NAME}
           git add deployment
           git add scripts/sbcli.lock
+          if [ -f scripts/operator.lock ]; then git add scripts/operator.lock; fi
           git commit -m "Auto-Build: Rebuild ${RELEASE_NAME}"
           git tag ${RELEASE_NAME}
           git rm scripts/sbcli.lock
+          if [ -f scripts/operator.lock ]; then git rm scripts/operator.lock; fi
           git commit -m "Auto-Build: Post Rebuild ${RELEASE_NAME}"
           git push --all
           git push --tags

.gitignore

@@ -5,4 +5,5 @@ venv
 .idea
 docs/reference/cli
 scripts/sbcli-repo
+scripts/operator-repo
 docs/reference/api/openapi.json

README.md

@@ -71,6 +71,38 @@ repositories to the latest commit.
 
 The command can be run at any time to update the external repositories to the latest commit.
 
+### Generating the Operator API Reference
+
+The operator API reference is generated from the Simplyblock operator Go API types. By default, the generator uses the
+`simplyblock-operator` checkout created by `./doc-builder update-repositories` at `./scripts/operator-repo`. If that
+checkout is not present, it falls back to a sibling checkout at `../simplyblock-manager` relative to this documentation
+repository:
+
+```bash
+./scripts/operator-reference-gen.sh
+```
+
+Alternatively, use the `doc-builder` wrapper, which uses the managed checkout and prints a helpful error if it is
+missing:
+
+```bash
+./doc-builder gen-operator-ref
+```
+
+To use a different checkout, set `OPERATOR_ROOT`:
+
+```bash
+OPERATOR_ROOT=/path/to/simplyblock-operator ./scripts/operator-reference-gen.sh
+```
+
+The `simplyblock-operator` checkout is pinned the same way the `sbcli` repository is (see the release process below). A
+`scripts/operator.lock` file, if present, pins the operator repository to a specific tag; otherwise the latest `HEAD` is
+used.
+
+The CI builders regenerate the operator API reference automatically after `./doc-builder update-repositories`, so
+pull request and development builds reflect the operator's latest `main`, while release builds reflect the pinned
+`operator.lock` tag. The generation requires Go, which is preinstalled on the GitHub runners.
+
 ### Serving Content Locally
 
 When building or updating the documentation, it is useful to have a local builder with live updating. Mkdocs supports
@@ -461,6 +493,13 @@ After pushing the new release branch, the GitHub action builder kicks in, builds
 website and updates the latest symlink, creates the necessary tag for history reasons, and merges the built
 documentation back into the `main` branch (folder `deployment`) using an auto-generated and auto-merged pull request. 
 
+As part of the build, the `sbcli` repository is pinned to the release version via `scripts/sbcli.lock`, and the
+`simplyblock-operator` repository is pinned via `scripts/operator.lock`. The operator lock is resolved automatically to
+the latest operator tag whose `MAJOR.MINOR` matches the release version — for example, release `26.2.4` resolves to the
+newest `v26.2.y` operator tag (the patch level may differ). If no matching operator tag exists (for example for older
+releases that predate the operator), the operator lock is skipped. Both lock files are committed on the version tag and
+removed again afterwards, so `main` never carries a pin.
+
 No further action is required.
 
 ### Updating an Existing Release

doc-builder

@@ -40,28 +40,48 @@ function ensure_docker_image() {
   exit 1
 }
 
-function update_repositories() {
-  if [ ! -d ./scripts/sbcli-repo ]; then
-    echo "Cloning sbcli repository..."
-    git clone https://github.com/simplyblock-io/sbcli.git ./scripts/sbcli-repo
-
-    if [ -f ./scripts/sbcli.lock ]; then
-      echo "Found sbcli.lock, checking out locked reference..."
-      pushd ./scripts/sbcli-repo
-      git checkout "$(cat ../sbcli.lock)"
+function update_repository() {
+  local name="$1"
+  local url="$2"
+  local dir="$3"
+  local lock="$4"
+
+  if [ ! -d "${dir}" ]; then
+    echo "Cloning ${name} repository..."
+    git clone "${url}" "${dir}"
+
+    if [ -f "${lock}" ]; then
+      local ref="$(cat "${lock}")"
+      echo "Found $(basename "${lock}"), checking out locked reference ${ref}..."
+      pushd "${dir}"
+      git checkout "${ref}"
       popd
     fi
   else
-    echo "Updating sbcli repository..."
-    pushd ./scripts/sbcli-repo
+    echo "Updating ${name} repository..."
+    pushd "${dir}"
     git reset --hard
     git pull -f
-    local ret=$?
     popd
-    exit ${ret}
   fi
 }
 
+function update_repositories() {
+  update_repository "sbcli" \
+    "https://github.com/simplyblock-io/sbcli.git" \
+    "./scripts/sbcli-repo" \
+    "./scripts/sbcli.lock"
+
+  # The operator repository is pinned to the latest tag matching the sbcli
+  # MAJOR.MINOR version (patch level may differ). The matching tag is resolved
+  # during the release and stored in ./scripts/operator.lock (see release.yaml
+  # and scripts/operator-lock.sh). Without a lock file, the latest HEAD is used.
+  update_repository "simplyblock-operator" \
+    "https://github.com/simplyblock/simplyblock-operator.git" \
+    "./scripts/operator-repo" \
+    "./scripts/operator.lock"
+}
+
 function build_image() {
   docker build -t ${IMAGE_NAME} .
   exit $?
@@ -90,6 +110,16 @@ function gen_sbcli_ref() {
   ${DOCKER} run --rm ${terminal} -v "${PWD}":/docs --entrypoint="/usr/local/bin/python" ${IMAGE_NAME} /docs/scripts/openapi-json-gen.py
 }
 
+function gen_operator_ref() {
+  if [ ! -d ./scripts/operator-repo ]; then
+    echo "The simplyblock-operator repository is not yet available. Please run ./doc-builder update-repositories and try again."
+    exit 1
+  fi
+
+  echo "Generating operator API reference..."
+  ./scripts/operator-reference-gen.sh
+}
+
 function build_css() {
   ${DOCKER} run --rm ${terminal} -v "${PWD}":/docs --entrypoint="/docs/scripts/build-css.sh" ${IMAGE_NAME}
 }
@@ -221,17 +251,31 @@ function run_help() {
       echo "                        with the same name."
     ;;
     "update-repositories")
-      echo "Updates the sbcli repository"
+      echo "Updates the sbcli and simplyblock-operator repositories"
       echo "./doc-builder update-repositories"
       echo
       echo "If a scripts/sbcli.lock file, with a specific tag name or git hash reference"
       echo "exists, the sbcli git subrepository will be checked out to this specific"
       echo "reference. Otherwise, it will be the latest HEAD."
+      echo
+      echo "The same applies to the simplyblock-operator repository via a"
+      echo "scripts/operator.lock file. The operator lock is resolved during the release"
+      echo "to the latest operator tag matching the sbcli MAJOR.MINOR version."
     ;;
     "gen-sbcli-ref")
       echo "Generates the sbcli / sbctl reference documentation"
       echo "./doc-builder gen-sbcli-ref"
     ;;
+    "gen-operator-ref")
+      echo "Generates the simplyblock-operator API reference documentation"
+      echo "./doc-builder gen-operator-ref"
+      echo
+      echo "Regenerates docs/reference/operator-api.md from the operator repository"
+      echo "checked out at ./scripts/operator-repo (see ./doc-builder update-repositories)."
+      echo "Requires Go to be installed. When a scripts/operator.lock file exists, the"
+      echo "operator repository is pinned to that reference; otherwise the latest HEAD is"
+      echo "used."
+    ;;
     *)
       echo "Unknown command. No help available."
     ;;
@@ -290,12 +334,20 @@ case "$1" in
     gen_sbcli_ref
   ;;
 
+  "gen-operator-ref")
+    # Test for help requested
+    run_help "$1" "$2"
+
+    gen_operator_ref
+  ;;
+
   *)
     echo "Simplyblock Documentation Builder"
     echo "Available commands:"
     echo "  ./doc-builder build-image              Building required docker image"
     echo "  ./doc-builder update-repositories      Initialized or updated external repository"
     echo "  ./doc-builder gen-sbcli-ref            Generates the sbcli reference pages"
+    echo "  ./doc-builder gen-operator-ref         Generates the operator API reference page"
     echo "  ./doc-builder serve                    Live serving content changes"
     echo "  ./doc-builder build                    Building static documentation"
     echo "  ./doc-builder build-css                Building static CSS"

docs/deployments/kubernetes/index.md

@@ -43,7 +43,7 @@ The operator manages the following resources:
 | `Device`         | Manages NVMe devices on storage nodes                               |
 | `Task`           | Monitors cluster tasks                                              |
 
-For detailed CRD documentation, see [Simplyblock Operator](../../reference/operator.md).
+For detailed CRD documentation, see [Simplyblock Operator](../../reference/operator/index.md).
 
 ## Platform-Specific Notes
 

docs/deployments/kubernetes/k8s-control-plane.md

@@ -52,4 +52,4 @@ kubectl get pods -n simplyblock
 Once the cluster is created, proceed to [Deploy Storage Nodes](k8s-storage-plane.md) to add storage
 capacity and enable volume provisioning.
 
-For a complete reference of all CRD fields, see [Simplyblock Operator](../../reference/operator.md).
+For a complete reference of all CRD fields, see [Simplyblock Operator](../../reference/operator/index.md).

docs/deployments/kubernetes/k8s-storage-plane.md

@@ -167,7 +167,7 @@ When the status becomes `active`, the operator automatically creates a `simplybl
 There is no necessity to manage this secret manually. The operator keeps it up to date and removes the cluster entry
 when the cluster is deleted.
 
-For a full list of configuration options see [Simplyblock Operator: StorageNodeSet](../../reference/operator.md#storagenodeset).
+For a full list of configuration options see [Simplyblock Operator: StorageNodeSet](../../reference/operator/reference.md#storagenodeset).
 
 !!! warning
     Simplyblock exclusively owns the resources it has been allocated. It must be ensured they are sized correctly
@@ -209,7 +209,7 @@ Once the pool is active, the operator automatically creates a StorageClass named
 `simplyblock-simplyblock-cluster-production-pool`.
 
 The StorageClass is automatically removed when the storage pool is deleted. For full details and customization options
-are available at [Simplyblock Operator: Storage Pool](../../reference/operator.md#storage-pool).
+are available at [Simplyblock Operator: Storage Pool](../../reference/operator/reference.md#pool).
 
 ```bash title="Check the StorageClass"
 kubectl get storageclass simplyblock-simplyblock-production-my-pool

docs/maintenance-operations/operator-cluster-operations.md

@@ -179,7 +179,7 @@ kubectl get storagenodeops migrate-worker-1 -n simplyblock -w
 ```
 
 The operation progresses through sub-phases: `Preparing → Restarting → Promoting`. See
-[StorageNodeOps: migrate](../reference/operator.md#migrating-a-storage-node-to-a-different-worker-migrate)
+[StorageNodeOps: migrate](../reference/operator/index.md#migrating-a-storage-node-to-a-different-worker-migrate)
 for full details including `newSsdPcie` and `reattachVolume` options.
 
 ### Draining and Removing a Node