Documentation update

.github/workflows/docs.yaml → .github/workflows/publish-docs.yaml

@@ -1,21 +1,18 @@
-name: docs
+name: publish-docs
 on:
   push:
     paths:
       # Only run this workflow if there are changes in any of these files.
       - .github/workflows/**
       - docs/**
-  pull_request:
-    paths:
-      # Only run this workflow if there are changes in any of these files.
-      - .github/workflows/**
-      - docs/**
+    branches:
+      - main
 defaults:
   run:
     working-directory: docs
 
 jobs:
-  deploy:
+  deploy-docs:
     runs-on: ubuntu-latest
     steps:
       - name: Get code
@@ -32,12 +29,13 @@ jobs:
       - name: Deploy website
         # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
         uses: peaceiris/actions-gh-pages@v3
-        # Only run this on pushes to the `main` branch (try-docusaurus-base is temporary for testing)
-        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/try-docusaurus-base'
+        # Only run this on pushes to the `docs`
+        if: github.ref == 'refs/heads/docs'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          # Build output to publish to the `gh-pages` branch:
           publish_dir: ./docs/build
+          #TODO: setup a staging directory when doing a PR
+          #destination_dir: staging
           # The following lines assign commit authorship to the official
           # GH-Actions bot for deploys to `gh-pages` branch:
           # https://github.com/actions/checkout/issues/13#issuecomment-724415212

.github/workflows/test-integ.yaml

@@ -1,6 +1,10 @@
 # Run integration tests against the integ API endpoint
 name: test integ
-on: [push]
+on:
+  push:
+    branches:
+      - main
+  pull_request:
 jobs:
   run-tests:
     runs-on: ubuntu-20.04
@@ -16,14 +20,14 @@ jobs:
       matrix:
         python-version: [
             #"3.6",   # Default on Ubuntu18.04 but openapi-generator fails
-            "3.7", 
-            "3.8", 
-            "3.9", 
-            "3.10", 
+            "3.7",
+            "3.8",
+            "3.9",
+            "3.10",
             "3.11",
-        ]
-        install_numpy: [ true, false ]
-        install_pillow: [ true, false ]
+          ]
+        install_numpy: [true, false]
+        install_pillow: [true, false]
     env:
       # This is associated with the "sdk-integ-test" user, credentials on 1password
       GROUNDLIGHT_API_TOKEN: ${{ secrets.GROUNDLIGHT_API_TOKEN }}

.gitignore

@@ -166,3 +166,5 @@ node_modules/
 
 *.swp
 **/.python-version
+
+.DS_Store

README.md

@@ -1,8 +1,8 @@
 # Groundlight Python SDK
 
-Check out our [documentation here](https://groundlight.github.io/python-sdk/docs/getting-started)!
+Groundlight makes it simple to build reliable visual applications.  Read the [full documentation here](https://code.groundlight.ai/python-sdk/).
 
-## Computer vision made simple
+## Computer Vision powered by Natural Language
 
 ```bash
 pip install groundlight
@@ -24,3 +24,13 @@ print(f"The answer is {image_query.result}")
 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._
+
+## Learn more
+
+Some more resources you might like:
+
+* [Code Documentation](https://code.groundlight.ai/)
+* [Python SDK](https://pypi.org/project/groundlight/)
+* [Company](https://www.groundlight.ai/)
+* [Login to Groundlight](https://app.groundlight.ai/)
+

docs/docs/building-applications/_category_.json

@@ -3,6 +3,6 @@
   "position": 2,
   "link": {
     "type": "generated-index",
-    "description": "Let's build some apps!"
+    "description": "Let's build some reliable vision applications."
   }
 }

docs/docs/building-applications/edge.md

@@ -7,4 +7,4 @@ from groundlight import Groundlight
 gl = Groundlight(endpoint="http://localhost:6717")
 ```
 
-(Edge model download is not yet generally available.)
+(Edge model download is not yet generally available.  Work with your Solutions Engineer to set up edge inference.)

docs/docs/getting-started/getting-started.mdx

@@ -1,6 +1,6 @@
 # Getting Started
 
-## Computer vision made simple
+## Computer Vision powered by Natural Language
 
 Build a working computer vision system in just 5 lines of python:
 

docs/docs/getting-started/managing-confidence.md

@@ -15,7 +15,8 @@ print(f"The answer is {image_query.result}")
 
 :::tip
 
-Add a tip here!
+Tuning confidence lets you balance accuracy against latency.
+Higher confidence will get higher accuracy, but will generally require longer latency.
 
 :::
 

docs/docs/installation/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Installation",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Installing on various platforms"
+  }
+}

docs/docs/installation/libraries-numpy-pil.md

@@ -0,0 +1,41 @@
+# Numpy, PIL, OpenCV - using common libraries
+
+## Smaller is better!
+
+Groundlight is optimized to run on small edge devices.  As such, you can use the Groundlight SDK without
+installing large libraries like `numpy` or `PIL` or `OpenCV`.
+
+But if you're already installing them, we'll use them.  Our SDK detects if these libraries are installed
+and will make use of them if they're present.  If not, we'll gracefully degrade, and tell you what's
+wrong if you try to use these features.
+
+## Numpy
+
+The Groundlight SDK can accept images as `numpy` arrays.  They should be in the standard HWN format in RGB color order.
+Pixel values should be from 0-255 (not 0.0-1.0 as floats). SO `uint8` data type is preferable since it saves memory.
+
+Here's sample code to create an 800x600 random image in numpy:
+
+```
+import numpy as np
+
+img = np_img = np.random.uniform(0, 255, (600, 800, 3))
+```
+
+## PIL
+
+The Groundlight SDK can accept PIL images directly in `submit_image_query`.
+
+
+## OpenCV
+
+OpenCV creates images that are stored as numpy arrays.  So can send them to `submit_image_query` directly.
+<b>BUT!</b> OpenCV uses BGR color order, not RGB.  You can reverse them as follows:
+
+```
+rgb_img = bgr_img[:, :, ::-1]
+```
+
+See [Issue #34](https://github.com/groundlight/python-sdk/issues/34) for a discussion about OpenCV support.
+
+

docs/docs/installation/linux-windows-mac.md

@@ -0,0 +1,16 @@
+# Windows, Linux, Mac
+
+Installation on common platforms is simple.  Just get `python3`, `pip`, and you're ready to go.
+
+## Python 3.7 or newer
+
+Groundlight's SDK supports Python 3.7 - 3.11.
+
+## Install the library
+
+Make sure you have the latest version by running:
+
+```
+pip3 install groundlight --upgrade
+```
+

docs/docs/installation/raspberry-pi-jetson.md

@@ -0,0 +1,20 @@
+# Raspberry Pi and NVIDIA Jetson
+
+Groundlight's SDK works great on ARM devices like Raspberry Pi and NVIDIA Jetson.
+
+```
+pip3 install groundlight
+```
+
+an ARM-compatible version will automatically get installed.
+
+## Streams
+
+If you have `docker` installed on your Pi, you can even just run 
+
+```
+docker run groundlight/stream
+```
+
+as we publish an ARM version of our streaming application to dockerhub.
+

docs/docs/building-applications/installation-faqs.md → docs/docs/installation/ubuntu-18.md

@@ -1,8 +1,6 @@
-# Instructions for common platforms
+# Ubuntu 18.04
 
-### Ubuntu 18.04
-
-Ubuntu 18.04 still uses python 3.6 by default, which is end-of-life. We recommend setting up python 3.8 as follows:
+Ubuntu 18.04 still uses python 3.6 by default, which is end-of-life. We generally recommend using python 3.10.  If you know how to install py3.10, please go ahead.  But the easiest version of python 3 to use with Ubuntu 18.04 is python 3.8, which can be installed as follows:
 
 ```shell
 # Prepare Ubuntu to install things