Merge pull request #11 from taskbadger/sk/basic-ops

update docs with cli basic ops and more

docs/cli.md

@@ -11,10 +11,18 @@ without the need to write any code.
 
 The CLI is bundled with the Python client library. To install it you need:
 
-* Python > X
+* Python > 3.7
+
+The recommended approach is to install the CLI into a virtual environment using [pipx](https://pypa.github.io/pipx/):
+
+```shell
+$ pipx install taskbadger
+```
+
+Alternatively you can install it into your user environment using pip:
 
 ```shell
-$ python -m pip install -U taskbadger
+$ python3 -m pip install --user taskbadger
 ```
 
 ## Monitoring processes
@@ -33,7 +41,19 @@ will be `success` if the command has a zero exit code. Any other exit code
 will result in an `error` status and the exit code will be saved in the
 task data under the `return_code` key.
 
-### Actions
+## Basic commands
+
+The CLI has a number of basic commands that allow you to interact with the Task Badger
+API. The commands are:
+
+* `list` - List tasks
+* `get` - Get a task
+* `create` - Create a task
+* `update` - Update a task
+
+For more details on these commands run `taskbadger <command> --help`.
+
+## Actions
 
 You can create actions for CLI tasks using the `--action` (`-a`) argument. The
 format for this argument is string with three components, separated by a space:

docs/index.md

@@ -202,6 +202,6 @@ The value may also be updated to 100.
     ```
 Also check your email to see if you got the notification.
 
-!!! tip "Up Next"
+## A real example
 
-    Take a look at how to apply this to a real [example](web_example.md).
+Take a look at how to apply this to a real [example](web_example.md).

docs/python.md

@@ -26,6 +26,9 @@ taskbadger.init(
 
 Details about these configuration parameters can be found [here](basics.md#organization-and-project)
 
+If you attempt to use the SDK without configuring it you will get an error. To avoid this you can use the
+[safe functions](#safe-functions) which will log any errors to the `taskbadger` logger.
+
 ## Usage
 
 The SDK provides a [Task](#taskbadger.Task) class which offers a convenient interface to the API.
@@ -61,6 +64,19 @@ task = Task.get(task_id)
 The task object provides methods for updating the properties of a task, adding custom data
 and adding actions.
 
+### Connection management
+
+The SDK will open a new connection for each request and close it when the request is complete. For instances
+where you wish to make multiple requests you can use the `taskbadger.Session` context manager:
+
+```python
+from taskbadger import Session
+
+with Session() as session:
+    task = Task.create("my task")
+    task.update(status="success")
+```
+
 ## Python Reference
 
 ::: taskbadger.Task

docs/web_example.md

@@ -7,7 +7,15 @@ and then updated it as the task is processed on the backend.
 
 In the following example we'll be using Django and Celery.
 
-## 1. Create the task in a view
+!!! tip
+
+    If using the Task Badger task for local progress tracking seems a bit heavy for your use case, you could
+    use [celery-progress](https://pypi.org/project/celery-progress/){:target="_blank"} for local tracking and
+    maintain the Task Badger task purerly for remote tracking, metrics, alerts, integrations etc.
+
+## Option 1: Use the Core API
+
+### 1. Create the task in a view
 
 ```python title="views.py"
 from django.conf import settings
@@ -33,7 +41,7 @@ def export_data(request):
 In addition to creating the task, we've also added an action so that we will get notified if the task
 fails or does not complete.
 
-## 2. Update the task 
+### 2. Update the task 
 
 ```python title="tasks.py"
 from celery.app import shared_task
@@ -55,7 +63,7 @@ def export_user_data(task_id, user_id):
     task.success(100)
 ```
 
-## 3. Expose the task status for the UI
+### 3. Expose the task status for the UI
 
 ```python title="views.py"
 @require_GET
@@ -68,3 +76,48 @@ def poll_task_status(request, task_id):
         "value_percent": task.value_percent
     })
 ```
+
+
+## Option 2: Use the Celery integration
+
+Use the Task Badger Celery Task class as the base class for your Celery task:
+
+```python title="tasks.py"
+from celery.app import shared_task
+from taskbadger.celery import Task
+
+@shared_task(bind=True, base=Task, taskbadger_kwargs={
+    "actions": [Action("error,stale", integration=EmailIntegration(to=settings.ADMINS[0][1]))],
+    "stale_timeout": 5
+})
+def export_user_data(self, user_id):
+    task = self.taskbadger_task
+
+    try:
+        compile_export(task, user_id)  # this also updates the task progress
+    except Exception as e:
+        task.error(data={
+            "error": str(e)
+        })
+        raise
+
+    task.success(100)
+```
+
+In the view we can get the Task Badger task ID from the Celery task result:
+
+```python title="views.py"
+from apps.export.tasks import export_user_data
+
+
+@require_POST
+def export_data(request):
+    task = export_user_data.delay(user_id=request.user.id, taskbadger_data={"user_id": request.user.id})
+    tb_task_id = task.info.get("taskbadger_task_id")
+    return JsonResponse({"task_id": tb_task_id})
+
+
+@require_GET
+def poll_task_status(request, task_id):
+    # same as above
+```

mkdocs.yml

@@ -14,6 +14,8 @@ theme:
     - content.code.copy
     - content.tabs.link
     - search.highlight
+    - navigation.instant
+    - navigation.footer
 markdown_extensions:
   - admonition
   - tables
@@ -39,6 +41,12 @@ extra:
   analytics:
     provider: google
     property: G-018PZFQ3EE
+  social:
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/@task_badger
+    - icon: fontawesome/brands/github
+      link: https://github.com/taskbadger
+copyright: Copyright © 2020 - 2023 Simon Kelly
 nav:
   - 'index.md'
   - 'basics.md'