Cleaning up and expanding documentation (#45)

Improving docs CICD to ensure docs build.

Adding new docs pages on several topics.

Cleaning up existing documentation.

Author: robotrapta

.github/workflows/cicd.yaml

@@ -64,12 +64,32 @@ jobs:
           # This is associated with the "sdk-test-prod" user, credentials on 1password
           GROUNDLIGHT_API_TOKEN: ${{ secrets.GROUNDLIGHT_API_TOKEN_PROD }}
 
+  # Check that the docs build.  (No broken links, etc.)
+  test-docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs/
+    steps:
+      - name: Get code
+        uses: actions/checkout@v3
+      - name: Setup npm
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+      - name: Install dependencies
+        run: npm install
+      - name: Build website
+        run: npm run build
+
   # Run integration tests against the API (only on the main branch, though). The comprehensive
   # version runs a matrix of python versions for better coverage.
   test-comprehensive:
     if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
     needs:
       - test-simple
+      - test-docs
     runs-on: ubuntu-latest
     strategy:
       # It's totally debatable which is better here: fail-fast or not.
@@ -192,7 +212,7 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/build
-          #TODO: setup a staging directory when doing a PR
+          # Someday we might want to set the destination to a staging dir for PR's
           #destination_dir: staging
           # The following lines assign commit authorship to the official
           # GH-Actions bot for deploys to `gh-pages` branch:

README.md

@@ -12,22 +12,19 @@ Build a working computer vision system in just a few lines of python:
 
 ```python
 from groundlight import Groundlight
-from PIL import Image
-import requests
 
 gl = Groundlight()
-d = gl.get_or_create_detector(name="doorway", query="Is the doorway open?")
-image_url = "https://images.selfstorage.com/large-compress/2174925f24362c479b2.jpg"
-image = Image.open(requests.get(image_url, stream=True).raw)
-image_query = gl.submit_image_query(detector=d, image=image)
+det = gl.get_or_create_detector(name="doorway", query="Is the doorway open?")
+img = "./docs/static/img/doorway.jpg"  # Image can be a file or a Python object
+image_query = gl.submit_image_query(detector=det, image=img)
 print(f"The answer is {image_query.result}")
 ```
 
 ### How does it work?
 
 Your images are first analyzed by machine learning (ML) models which are automatically trained on your data. If those models have high enough confidence, that's your answer. But if the models are unsure, then the images are progressively escalated to more resource-intensive analysis methods up to real-time human review. So what you get is a computer vision system that starts working right away without even needing to first gather and label a dataset. At first it will operate with high latency, because people need to review the image queries. But over time, the ML systems will learn and improve so queries come back faster with higher confidence.
 
-_Note: The SDK is currently in "beta" phase. Interfaces are subject to change in future versions._
+_Note: The SDK is currently in "beta" phase. Interfaces are subject to change in future versions. We will follow [semver](https://semver.org/) semantics for breaking changes._
 
 ## Learn more
 

docs/README.md

@@ -1,41 +1,44 @@
-# Website
+# Documentation: code.groundlight.ai
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This part of the SDK repo contains all the code for the website at [code.groundlight.ai](https://code.groundlight.ai/)  It is built with [Docusaurus 2](https://docusaurus.io/).
 
-## Installation
+The docs are included with the SDK so that we can automate testing of the code samples in the documentation.  This way we can ensure that the code samples in our docs always work with the current SDK.
 
-```shell
+## Previewing doc changes
+
+Doc changes are published automatically when they're merged to main.  To preview changes, build and host the site locally.  You'll need a reasonably modern version of `npm` and then:
+
+<<<<<<< HEAD
+```
 npm install
+npm run build  # looks for any errors
+npm start  # starts interactive server
 ```
 
-## Local Development
+and then open [http://localhost:3000/python-sdk](http://localhost:3000/python-sdk).
 
-```shell
-npm start
-```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+## Running docs tests
 
-### Build
+You'll need python poetry and make installed.  And you'll need an API Token configured.  Then you can just run:
 
-```shell
-npm run build
+```
+make test-docs
+```
+=======
+```
+npm install
+npm start
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
-### Deployment
+and then open [http://localhost:3000/python-sdk](http://localhost:3000/python-sdk).
 
-Using SSH:
 
-```shell
-USE_SSH=true npm run deploy
-```
+## Running docs tests
 
-Not using SSH:
+You'll need python poetry and make installed.  And you'll need an API Token configured.  Then you can just run:
 
-```shell
-GIT_USER=<Your GitHub username> npm run deploy
 ```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+make test-docs
+```
+>>>>>>> origin/docs-applications

docs/docs/building-applications/_category_.json

@@ -1,8 +1,4 @@
 {
   "label": "Building Applications",
-  "position": 2,
-  "link": {
-    "type": "generated-index",
-    "description": "Let's build some reliable vision applications."
-  }
+  "position": 2
 }

docs/docs/building-applications/building-applications.md

@@ -0,0 +1,47 @@
+# Building Applications
+
+Groundlight provides a powerful "computer vision powered by natural language" system that enables you to build visual applications with minimal code. With Groundlight, you can quickly create applications for various use cases, from simple object detection to complex visual analysis.
+
+In this page, we'll introduce you to some sample applications built using Groundlight and provide links to more detailed guides on various topics.
+
+## Sample Applications
+
+Explore these GitHub repositories to see examples of Groundlight-powered applications:
+
+### Groundlight Stream Processor
+
+Repository: [https://github.com/groundlight/stream](https://github.com/groundlight/stream)
+
+The Groundlight Stream Processor is an easy-to-use Docker container for analyzing RTSP streams or common USB-based cameras. You can run it with a single Docker command, such as:
+
+```bash
+docker run stream:local --help
+```
+
+### Arduino ESP32 Camera Sample App
+
+Repository: [https://github.com/groundlight/esp32cam](https://github.com/groundlight/esp32cam)
+
+This sample application allows you to build a working AI vision detector using an inexpensive WiFi camera. With a cost of under $10, you can create a powerful and affordable AI vision system.
+
+### Raspberry Pi
+
+Repository: [https://github.com/groundlight/raspberry-pi-door-lock](https://github.com/groundlight/raspberry-pi-door-lock)
+
+This sample application demonstrates how to set up a Raspberry Pi-based door lock system. The application monitors a door and sends a notification if the door is observed to be unlocked during non-standard business hours.
+
+### Industrial and Manufacturing Applications
+
+Groundlight can be used to [apply modern natural-language-based computer vision to industrial and manufacturing applications](/docs/building-applications/industrial).
+
+## Further Reading
+
+For more in-depth guides on various aspects of building applications with Groundlight, check out the following pages:
+
+- [Working with Detectors](working-with-detectors.md): Learn how to create, configure, and use detectors in your Groundlight-powered applications.
+- [Using Groundlight on the edge](edge.md): Discover how to deploy Groundlight in edge computing environments for improved performance and reduced latency.
+- [Handling HTTP errors](handling-errors.md): Understand how to handle and troubleshoot HTTP errors that may occur while using Groundlight.
+
+By exploring these resources and sample applications, you'll be well on your way to building powerful visual applications using Groundlight's computer vision and natural language capabilities.
+
+

docs/docs/building-applications/handling-errors.md

@@ -1,19 +1,66 @@
-# Handling HTTP errors
+# Handling Server Errors
 
-If there is an HTTP error during an API call, it will raise an `ApiException`. You can access different metadata from that exception:
+When building applications with the Groundlight SDK, you may encounter server errors during API calls. This page covers how to handle such errors and build robust code that can gracefully handle exceptions.
 
-```python
+## Handling ApiException
+
+If there is an HTTP error during an API call, the SDK will raise an `ApiException`. You can access different metadata from that exception:
+
+```python notest
+import traceback
 from groundlight import ApiException, Groundlight
 
 gl = Groundlight()
 try:
-    detectors = gl.list_detectors()
+    d = gl.get_or_create_detector(
+        "Road Checker", 
+        "Is the site access road blocked?")
+    iq = gl.submit_image_query(d, get_image(), wait=60)
 except ApiException as e:
-    # Many fields available to describe the error
-    print(e)
-    print(e.args)
-    print(e.body)
-    print(e.headers)
-    print(e.reason)
-    print(e.status)
+    # Print a traceback for debugging
+    traceback.print_exc()
+
+    # e.reason contains a textual description of the error
+    print(f"Error reason: {e.reason}")
+
+    # e.status contains the HTTP status code
+    print(f"HTTP status code: {e.status}")
+
+    # Common HTTP status codes:
+    # 400 Bad Request: The request was invalid or malformed
+    # 401 Unauthorized: Your GROUNDLIGHT_API_TOKEN is missing or invalid
+    # 403 Forbidden: The request is not allowed due to insufficient permissions
+    # 404 Not Found: The requested resource was not found
+    # 429 Too Many Requests: The rate limit for the API has been exceeded
+    # 500 Internal Server Error: An error occurred on the server side
 ```
+
+## Best Practices for Handling Exceptions
+
+When working with the Groundlight SDK, follow these best practices to handle exceptions and build robust code:
+
+### Catch Specific Exceptions
+
+Catch only the specific exceptions that you expect to be raised, such as `ApiException`. Avoid catching broad exceptions like `Exception`, as it may make debugging difficult and obscure other unrelated issues.
+
+### Use Custom Exception Classes
+
+Consider creating custom exception classes for your application-specific errors. This can help you differentiate between errors originating from the Groundlight SDK and those from your application.
+
+### Log Exceptions
+
+Log exceptions with appropriate log levels (e.g., error, warning, etc.) and include relevant context information. This will help you debug issues more effectively and monitor the health of your application.
+
+### Implement Retry Logic
+
+When handling exceptions, implement retry logic with exponential backoff for transient errors, such as network issues or rate-limiting. This can help your application recover from temporary issues without manual intervention.
+
+### Handle Exceptions Gracefully
+
+In addition to logging exceptions, handle them gracefully to ensure that your application remains functional despite errors. This might include displaying an error message to users or falling back to a default behavior.
+
+### Test Your Error Handling
+
+Write tests to ensure that your error handling works as expected. This can help you catch issues early and ensure that your application can handle errors gracefully in production.
+
+By following these best practices, you can create robust and resilient applications that can handle server errors and other exceptions when using the Groundlight SDK.

docs/docs/building-applications/industrial.md

@@ -0,0 +1,23 @@
+# Industrial and Manufacturing Applications
+
+Modern natural language-based computer vision is transforming industrial and manufacturing applications by enabling more intuitive interaction with automation systems. Groundlight offers cutting-edge computer vision technology that can be seamlessly integrated into various industrial processes, enhancing efficiency, productivity, and quality control.
+
+## Machine Tending
+
+Groundlight's computer vision technology can assist in automating machine-tending tasks, such as loading and unloading materials in CNC machines, milling centers, or injection molding equipment. By enabling robots to recognize parts and tools using natural language, complex machine-tending tasks become more accessible and efficient.
+
+## Process Automation
+
+Integrating Groundlight's computer vision into your process automation systems can help identify bottlenecks, optimize workflows, and reduce manual intervention. Our technology can work hand-in-hand with robotic systems to perform tasks like sorting, assembly, all while interpreting natural language commands to streamline operations.
+
+## Quality Control
+
+Groundlight's computer vision technology can play a vital role in ensuring the highest quality standards in your manufacturing processes. By identifying defects or irregularities in products, our computer vision system can help maintain strict quality control, reducing the need for manual inspections and increasing overall product quality.
+
+## Integration with Cobots and CNC Machines
+
+Groundlight's computer vision technology can be easily integrated with popular cobot robotic arms, such as Universal Robots, to enhance their capabilities and improve collaboration between humans and robots. Additionally, our technology can be integrated into existing CNC machines or other devices using the Modbus interface, allowing for seamless communication and control within your manufacturing environment.
+
+# Contact Sales
+
+To learn more about how Groundlight's natural language computer vision technology can revolutionize your industrial and manufacturing processes, please reach out to us at [[email protected]](mailto:[email protected]).

docs/docs/getting-started/1-api-tokens.md

@@ -0,0 +1,69 @@
+# API Tokens
+
+## About API Tokens
+
+To use the Groundlight SDK or API, you need a security token which we call an "API Token." These authenticate you to Groundlight and authorize your code to use services in your account.
+
+API tokens look like `api_2GdXMflhJ...` and consist of a ksuid (a kind of sortable UUID) followed by a secret string.
+
+## Handling API Tokens
+
+**You should treat API tokens like passwords.** Never check them directly into your code or share them. Please use best security practices with your API tokens, because if anybody gets your API token, they have nearly full control over your Groundlight account.
+
+Here are some best practices for handling API tokens:
+
+- Store API tokens in a secure location, such as an encrypted vault.
+- Use environment variables to store API tokens, rather than hardcoding them in your application.
+- Limit the number of people who have access to API tokens.
+- Rotate API tokens regularly and revoke old ones when they are no longer needed.
+
+## Using API Tokens with the SDK
+
+There are a couple of ways the SDK can find your API token:
+
+1. Environment variable (recommended): As a best practice, we recommend storing API tokens in the environment variable `GROUNDLIGHT_API_TOKEN`. This helps avoid accidentally committing the token to your code repository.  The SDK will automatically look for the API token there, so you don't have to put it in your code at all.
+
+```python
+from groundlight import Groundlight
+
+# looks for API token in environment variable GROUNDLIGHT_API_TOKEN
+gl = Groundlight()
+```
+
+2.  Constructor argument: Alternatively, you can pass the API token directly to the Groundlight constructor. However, be cautious not to commit this code to your repository.
+
+```
+from groundlight import Groundlight
+
+token = get_token_from_secure_location()
+gl = Groundlight(api_token=token)
+```
+
+## Creating and Revoking API Tokens
+You can manage your API tokens from the Groundlight website at [https://app.groundlight.ai/reef/my-account/api-tokens](https://app.groundlight.ai/reef/my-account/api-tokens).
+
+
+### Creating API Tokens
+
+1. Log in to your Groundlight account and navigate to the API tokens page.
+1. Click the "Create New API Token" button.
+1. Give the new token a descriptive name, so you can easily identify it later.
+1. Click "Create Token."
+1. Copy the generated token and store it securely, as you won't be able to see it again. Groundlight does not store a copy of your API tokens.
+
+### Viewing and Revoking API Tokens
+
+On the API tokens page, you can see a list of your current tokens, along with the following information:
+
+- Token Name: The descriptive name you assigned when creating the token
+- Snippet (prefix): A short, unique identifier for each token
+- Last used: The date and time the token was last used
+
+### To revoke an API token
+
+1. Locate the token you want to revoke in the list.
+1. Click the "Delete" button next to the token.
+1. Confirm that you want to revoke the token.
+
+Note: Revoking an API token will immediately invalidate it and prevent any applications using it from accessing your Groundlight account. Be sure to update your applications with a new token before revoking an old one.
+