ci: add workflow to check CLI documentation sync

Add GitHub workflow that verifies CLI documentation stays in sync with implementation. The workflow runs on PRs, generates current docs, compares with existing docs, and comments on PR if outdated.

Author: kaincenteno

.github/workflows/check-cli-docs.yml

@@ -0,0 +1,60 @@
+name: Check CLI Documentation
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  check-docs:
+    name: Verify CLI documentation is up-to-date
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Generate current CLI documentation
+        run: |
+          typer pyaxm.cli utils docs --name pyaxm-cli --output /tmp/cli.md
+
+      - name: Compare with existing documentation
+        id: compare_docs
+        run: |
+          # Calculate MD5 hashes for both files
+          OLD_HASH=$(md5sum docs/cli.md | awk '{ print $1 }')
+          NEW_HASH=$(md5sum /tmp/cli.md | awk '{ print $1 }')
+          
+          # Compare hashes
+          if [ "$OLD_HASH" != "$NEW_HASH" ]; then
+            echo "docs_outdated=true" >> $GITHUB_OUTPUT
+            exit 1
+          else
+            echo "CLI documentation is up-to-date."
+            echo "Hash: $OLD_HASH"
+            echo "docs_outdated=false" >> $GITHUB_OUTPUT
+          fi
+          
+      - name: Comment on PR if documentation is outdated
+        if: ${{ steps.compare_docs.outputs.docs_outdated == 'true' }}
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const pull_request_number = context.issue.number;
+            const comment = 'CLI Documentation Check Failed;
+            
+            github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pull_request_number,
+              body: comment
+            });

README.md

@@ -41,7 +41,19 @@ The token path is the location where the access token will be stored.
 ## CLI:
 A command-line interface (CLI) tool called `pyaxm-cli` is included for easy access to the API.
 
-For detailed usage instructions, available commands, options, and examples, please refer to the [CLI documentation](docs/cli.md).
+### Overview
+The CLI provides a convenient way to interact with the Apple Business Manager API directly from your terminal. It includes commands for managing devices, MDM servers, and retrieving device information.
+
+### Detailed Documentation
+For comprehensive documentation of all available commands, options, and usage examples, please refer to the [CLI documentation](docs/cli.md).
+
+### Updating Documentation
+The CLI documentation is automatically generated from the code. To update it after making changes to the CLI implementation, run:
+```bash
+typer pyaxm.cli utils docs --name pyaxm-cli --output docs/cli.md
+```
+
+A GitHub workflow automatically checks that the documentation stays in sync.
 
 # Client:
 Example usage:

pyaxm/cli.py

@@ -6,11 +6,11 @@
 from pyaxm.client import Client
 
 app = typer.Typer()
-client = Client()
 
 @app.command()
 def devices():
     """List all devices in the organization."""
+    client = Client()
     devices = client.list_devices()
     devices_data = []
     for device in devices:
@@ -23,6 +23,7 @@ def devices():
 @app.command()
 def device(device_id: Annotated[str, typer.Argument()]):
     """Get a device by ID."""
+    client = Client()
     device = client.get_device(device_id)
     device_info = {'id': device.id}
     device_info.update(device.attributes.model_dump())
@@ -32,6 +33,7 @@ def device(device_id: Annotated[str, typer.Argument()]):
 @app.command()
 def apple_care_coverage(device_id: Annotated[str, typer.Argument()]):
     """Get AppleCare coverage for a device."""
+    client = Client()
     coverage = client.get_apple_care_coverage(device_id)
     coverage_data = [item.attributes.model_dump() for item in coverage]
     df = pd.DataFrame(coverage_data)
@@ -40,6 +42,7 @@ def apple_care_coverage(device_id: Annotated[str, typer.Argument()]):
 @app.command()
 def mdm_servers():
     """List all MDM servers."""
+    client = Client()
     servers = client.list_mdm_servers()
     servers_data = []
     for server in servers:
@@ -52,6 +55,7 @@ def mdm_servers():
 @app.command()
 def mdm_server(server_id: Annotated[str, typer.Argument()]):
     """List devices in a specific MDM server."""
+    client = Client()
     devices = client.list_devices_in_mdm_server(server_id)
     devices_data = [{'id': device.id} for device in devices]
     df = pd.DataFrame(devices_data)
@@ -60,6 +64,7 @@ def mdm_server(server_id: Annotated[str, typer.Argument()]):
 @app.command()
 def mdm_server_assigned(device_id: Annotated[str, typer.Argument()]):
     """Get the server assignment for a device."""
+    client = Client()
     server_assignment = client.get_device_server_assignment(device_id)
     assignment_info = {'id': server_assignment.id}
     df = pd.DataFrame([assignment_info])
@@ -68,6 +73,7 @@ def mdm_server_assigned(device_id: Annotated[str, typer.Argument()]):
 @app.command()
 def assign_device(device_id: Annotated[List[str], typer.Argument()], server_id: Annotated[str, typer.Argument()]):
     """Assign one or more devices to an MDM server."""
+    client = Client()
     activity = client.assign_unassign_device_to_mdm_server(device_id, server_id, 'ASSIGN_DEVICES')
     activity_data = {'id': activity.id}
     activity_data.update(activity.attributes.model_dump())
@@ -77,6 +83,7 @@ def assign_device(device_id: Annotated[List[str], typer.Argument()], server_id:
 @app.command()
 def unassign_device(device_id: Annotated[List[str], typer.Argument()], server_id: Annotated[str, typer.Argument()]):
     """Unassign one or more devices from an MDM server."""
+    client = Client()
     activity = client.assign_unassign_device_to_mdm_server(device_id, server_id, 'UNASSIGN_DEVICES')
     activity_data = {'id': activity.id}
     activity_data.update(activity.attributes.model_dump())