docs: add examples for the cancel, approve, deny and test actions

.github/dependabot.yml

@@ -22,8 +22,9 @@ updates:
       - ci
 
   - package-ecosystem: pip
-    # the install_requires and extras_require lists, which Dependabot reads
-    # straight out of setup.py
+    # the dependencies and optional-dependencies tables in pyproject.toml, which
+    # is where the packaging metadata moved in #37. setup.py is version
+    # resolution only now and declares nothing to bump.
     directory: /
     schedule:
       interval: weekly

ascenderkit/cli/docs/source/examples.rst

@@ -56,6 +56,61 @@ alone:
     ascender jobs relaunch 42 --hosts failed
     ascender workflow_jobs relaunch 7 --nodes failed --wait
 
+Cancelling a Running Job
+------------------------
+
+Cancelling is available on every job resource: ``jobs``, ``workflow_jobs``,
+``project_updates``, ``inventory_updates``, ``ad_hoc_commands`` and
+``system_jobs``. The platform accepts the request and stops the job shortly
+after, so the status printed back can still read ``running``. Asking to cancel a
+job that has already finished returns the platform's own refusal:
+
+.. code:: bash
+
+    ascender jobs cancel 42
+    ascender workflow_jobs cancel 7 -f human
+    ascender project_updates cancel 13
+
+Approving or Denying a Workflow Approval
+----------------------------------------
+
+A workflow that reaches an approval node waits there until somebody answers it.
+Approving lets the workflow past the node, denying refuses it and fails the
+workflow. Both print the approval as it stands afterwards, so the status in the
+output is the one it has once the answer has landed:
+
+.. code:: bash
+
+    ascender workflow_approvals list -f human
+    ascender workflow_approvals approve 21
+    ascender workflow_approvals deny 22
+
+Testing a Notification Template or a Credential
+-----------------------------------------------
+
+Testing asks the platform to exercise a thing rather than describe it, on
+``notification_templates``, ``credentials`` and ``credential_types``. Testing a
+notification template sends one, and the reply names the notification it queued,
+whose own record carries the delivery status. Testing a lookup credential
+performs the lookup and reports what came back:
+
+.. code:: bash
+
+    ascender notification_templates test 3 -f human
+    ascender credentials test 9
+
+``--inputs`` and ``--metadata`` try values that are not saved yet, which is what
+the endpoint is for: trying a configuration before committing to it. Both take
+JSON or YAML, or ``@`` a file holding either:
+
+.. code:: bash
+
+    ascender credentials test 9 \
+        --metadata '{"secret_path": "/kv/prod", "secret_key": "password"}'
+    ascender credential_types test 12 \
+        --inputs '{"url": "https://vault.example.org", "token": "@~/.vault-token"}' \
+        --metadata @lookup.yml
+
 Updating a Job Template with Extra Vars
 ---------------------------------------