Merge pull request #24 from kaincenteno/cli-workflow-check

ci: add workflow to check CLI documentation sync

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())