Update deployment CD and CLI docs build (#212)

Update deploy to onto-ns CD workflow
Retrieve SHA for proper file comparison.

Update CLI docs generation CI job.
Add bash script to auto-update the CLI docs.

Update CLI documentation.

Add mongo-express to compose.

.github/workflows/cd_onto-ns.yml

@@ -10,26 +10,44 @@ on:
 jobs:
   check-service-changes:
     runs-on: ubuntu-latest
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
     outputs:
-      service-changes: ${{ steps.check-changes.outputs.service-changes }}
+      service-changes: ${{ steps.check-changes.outputs.service-changes || steps.passthrough.outputs.service-changes }}
 
     steps:
+      - name: Passthrough if manually deploying
+        if: github.event_name == 'workflow_dispatch'
+        id: passthrough
+        run: |
+          echo "service-changes=true" >> $GITHUB_OUTPUT
+
       - name: Checkout repository
+        if: github.event_name != 'workflow_dispatch'
         uses: actions/checkout@v4
 
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Download deployment artifact
+        if: github.event_name != 'workflow_dispatch'
+        uses: actions/download-artifact@v4
+        with:
+          name: onto-ns-deployment
+
       - name: Check changes
+        if: github.event_name != 'workflow_dispatch'
         id: check-changes
         run: |
           git fetch --all --quiet
 
-          git diff --name-only origin/main -- | \
-          grep -qE "(pyproject.toml|entities_service/((models/|service/)(.+/)*)?[^/]*\.py)" \
-          && SERVICE_CHANGES=true \
-          || SERVICE_CHANGES=false
+          before_sha="$(python -c "import json, pathlib; print(json.load(pathlib.Path('onto-ns-deployment.json').read_text())['before'])")"
+
+          git diff --name-only ${before_sha} -- | grep -qE "(pyproject.toml|entities_service/((models|service)/(.+/)*)?[^/]*\.py)" && SERVICE_CHANGES=true || SERVICE_CHANGES=false
 
           echo "Changed files:"
-          git diff --name-only origin/main --
+          git diff --name-only ${before_sha} --
           echo "SERVICE_CHANGES=${SERVICE_CHANGES}"
 
           echo "service-changes=${SERVICE_CHANGES}" >> $GITHUB_OUTPUT

.github/workflows/ci_tests.yml

@@ -367,25 +367,48 @@ jobs:
       - name: Build CLI docs
         run: |
           # Build the CLI documentation
-          # Run it twice, since the first run may create a doc only for the `config` sub-typer app.
-          typer entities_service.cli.main utils docs --output /tmp/CLI.md > /dev/null
+          # We need to run this multiple times until the documentation is generated
+          # properly. Sometimes it only finds the sub-app `config` and not the main
+          # app `entities-service`.
+          set +e
+
           typer entities_service.cli.main utils docs --output /tmp/CLI.md > /dev/null
+          until grep -q "# \`entities-service\`" /tmp/CLI.md; do
+            typer entities_service.cli.main utils docs --output /tmp/CLI.md > /dev/null
+          done
 
-          diff --suppress-common-lines /tmp/CLI.md docs/CLI.md 2>&1 > /tmp/CLI_diff.md && ERROR_CODE=0 || ERROR_CODE=$?
+          diff --suppress-common-lines /tmp/CLI.md docs/CLI.md > /dev/null 2>&1
 
           ERROR_CODE=$?
 
           if [ ${ERROR_CODE} -eq 2 ]; then
-            echo "diff encountered an error."
+            echo "❌ diff encountered an error."
             exit 2
           elif [ ${ERROR_CODE} -eq 1 ]; then
-            echo "CLI documentation has changed. Please update the documentation."
+            echo "✨ CLI documentation has changed."
+            echo "Please update the documentation by running './build_cli_docs.sh' in a bash-compatible terminal."
             echo "Diff:"
-            cat /tmp/CLI_diff.md
+            diff --suppress-common-lines --color /tmp/CLI.md docs/CLI.md
             exit 1
           elif [ ${ERROR_CODE} -eq 0 ]; then
-            echo "CLI documentation is up-to-date."
+            echo "👌 CLI documentation is up-to-date."
           else
-            echo "Unknown error."
+            echo "❌ Unknown error."
             exit 3
           fi
+
+  upload-artifact-for-onto-ns-deployment:
+    name: Upload artifact for onto-ns deployment
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Generate artifact
+        run: |
+          echo "{\"before\":\"${{ github.event.before }}\"}" > onto-ns-deployment.json
+
+      - name: Archive artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: onto-ns-deployment
+          path: onto-ns-deployment.json

build_cli_docs.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+{
+    typer --version > /dev/null 2>&1
+} || {
+    echo -e "\n❌ 'typer' is not installed." &&
+    echo -e "Please install it and the 'entities-service' CLI using:\n\n  pip install .[cli]\n" &&
+    exit 1
+}
+
+DOCS_PATH="docs/CLI.md"
+
+if [ ! -f ${DOCS_PATH} ]; then
+    echo "CLI documentation file not found at ${DOCS_PATH}."
+    exit 1
+fi
+
+rm /tmp/CLI.md 2> /dev/null
+
+# Generate CLI documentation
+typer entities_service.cli.main utils docs --output /tmp/CLI.md > /dev/null
+until grep -q "# \`entities-service\`" /tmp/CLI.md; do
+    typer entities_service.cli.main utils docs --output /tmp/CLI.md > /dev/null
+done
+
+diff --suppress-common-lines /tmp/CLI.md ${DOCS_PATH} > /dev/null 2>&1
+
+ERROR_CODE=$?
+
+if [ ${ERROR_CODE} -eq 2 ]; then
+    echo "❌ diff encountered an error."
+    exit 2
+elif [ ${ERROR_CODE} -eq 1 ]; then
+    echo "✨ CLI documentation will be updated."
+    echo "Diff:"
+    diff --suppress-common-lines --color /tmp/CLI.md ${DOCS_PATH}
+    mv -f /tmp/CLI.md ${DOCS_PATH}
+    echo -e "\nNow commit the changes to the documentation file:\n\n  git add ${DOCS_PATH}\n  git commit -m 'Update CLI documentation'\n"
+elif [ ${ERROR_CODE} -eq 0 ]; then
+    echo "👌 CLI documentation is up-to-date."
+else
+    echo "❌ Unknown error."
+    exit 3
+fi

compose.yml

@@ -26,7 +26,6 @@ services:
 
   mongodb:
     image: mongo:8
-    restart: always
     ports:
       - "27017:27017"
     networks:
@@ -42,5 +41,22 @@ services:
       retries: 5
     stop_grace_period: 1s
 
+  mongodb_gui:
+    image: mongo-express:1
+    ports:
+      - "8081:8081"
+    environment:
+      ME_CONFIG_MONGODB_URL: mongodb://root:root@mongodb:27017/?authSource=admin
+      ME_CONFIG_MONGODB_PORT: 27017
+      ME_CONFIG_MONGODB_ENABLE_ADMIN: "true"
+      ME_CONFIG_BASICAUTH_USERNAME: admin
+      ME_CONFIG_BASICAUTH_PASSWORD: admin
+    networks:
+      - entities_service_net
+    depends_on:
+      mongodb:
+        condition: service_healthy
+        restart: true
+
 networks:
   entities_service_net:

docs/CLI.md

@@ -19,6 +19,7 @@ $ entities-service [OPTIONS] COMMAND [ARGS]...
 **Commands**:
 
 * `config`: Manage configuration options.
+* `list`: List resources.
 * `login`: Login to the entities service.
 * `upload`: Upload (local) entities to a remote location.
 * `validate`: Validate (local) entities.
@@ -112,6 +113,58 @@ $ entities-service config unset-all [OPTIONS]
 
 * `--help`: Show this message and exit.
 
+## `entities-service list`
+
+List resources.
+
+**Usage**:
+
+```console
+$ entities-service list [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `entities`: List entities from the entities service.
+* `namespaces`: List namespaces from the entities service.
+
+### `entities-service list entities`
+
+List entities from the entities service.
+
+**Usage**:
+
+```console
+$ entities-service list entities [OPTIONS] [NAMESPACE]...
+```
+
+**Arguments**:
+
+* `[NAMESPACE]...`: Namespace(s) to list entities from. Defaults to the core namespace. If the namespace is a URL, the specific namespace will be extracted.
+
+**Options**:
+
+* `-a, --all`: List entities from all namespaces.
+* `--help`: Show this message and exit.
+
+### `entities-service list namespaces`
+
+List namespaces from the entities service.
+
+**Usage**:
+
+```console
+$ entities-service list namespaces [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
 ## `entities-service login`
 
 Login to the entities service.

pyproject.toml

@@ -54,7 +54,7 @@ dependencies = [
 cli = [
     "httpx-auth ~=0.22.0",
     "pyyaml ~=6.0",
-    "typer[all] ~=0.12.5",
+    "typer ~=0.12.5",
 ]
 testing = [
     "cryptography ~=43.0",