Documenation Improvements and Updates (#279)

# Changes (selected)
1. Update documentation to reflect that we support Python 3.9+
2. Document usage of `ask_ml` and `ask_confident`
3. Reorganize site to improve consistency and flow (most significantly,
docs for *developing* applications are separate from docs detailing
*sample* applications)
4. Document use of `framegrab` and tuning of motion detection
5. Document `Alerts`, update documentation for the `edge-endpoint` and
`groundlight/stream`

---------

Co-authored-by: Brandon <[email protected]>
Co-authored-by: Paulina Varshavskaya <[email protected]>

.github/workflows/cicd.yaml

@@ -6,7 +6,7 @@ on:
   push:
 
 env:
-  PYTHON_VERSION: "3.10"
+  PYTHON_VERSION: "3.11"
   POETRY_VERSION: "1.7.1"
 jobs:
   # Run our linter on every push to the repository.
@@ -65,7 +65,7 @@ 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.)
+  # Check that the docs build. (No broken links, etc.)
   test-docs:
     runs-on: ubuntu-latest
     defaults:
@@ -77,14 +77,14 @@ jobs:
       - name: Setup npm
         uses: actions/setup-node@v3
         with:
-          node-version: 18
+          node-version: 21
           cache: npm
       - name: Install dependencies
         run: npm install
       - name: Build website
         run: npm run build
 
-    # Checks that the API reference docs built with shpinx build
+  # Checks that the API reference docs built with sphinx build
   test-api-reference-docs:
     runs-on: ubuntu-latest
     steps:
@@ -94,14 +94,17 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-      - name: install poetry
+      - name: Install poetry
         uses: snok/install-poetry@v1
         with:
           version: ${{ env.POETRY_VERSION }}
-
+      - name: Setup npm
+        uses: actions/setup-node@v3
+        with:
+          node-version: 21
+          cache: npm
       - name: Install dependencies
         run: make install-sphinx-deps
-
       - name: Build API documentation
         run: |
           make apidocs
@@ -135,6 +138,7 @@ jobs:
             "3.10",
             "3.11",
             "3.12",
+            "3.13",
           ]
         install_extras: [true, false]
     steps:
@@ -257,7 +261,7 @@ jobs:
       - name: Setup npm
         uses: actions/setup-node@v3
         with:
-          node-version: 18
+          node-version: 21
           cache: npm
       - name: Install dependencies
         run: npm install
@@ -292,8 +296,7 @@ jobs:
     runs-on: ubuntu-latest
     needs:
       - test-comprehensive
-      # For now, we'll require the comprehensive tests to succeed, but not the linter checks.
-      # - lint
+      - lint
     env:
       POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_PUBLISH_TOKEN }}
     steps:

.pylintrc

@@ -46,7 +46,7 @@ persistent=yes
 
 # Min Python version to use for version dependend checks. Will default to the
 # version used to run pylint.
-py-version=3.8
+py-version=3.9
 
 # When enabled, pylint would attempt to guess common misconfiguration and emit
 # user-friendly hints instead of false-positive error messages.

DEVELOPING.md

@@ -14,7 +14,7 @@ you can install the package dependencies by running:
 make install
 ```
 
-Note: We support Python 3.8+ for clients of the SDK, but we recommend developing with Python 3.10+.
+Note: We support Python 3.9+ for clients of the SDK, but we recommend developing with Python 3.10+.
 
 ### Run tests
 

Makefile

@@ -1,4 +1,8 @@
-.PHONY: apidocs docs-comprehensive generate html install install-dev install-extras install-generator install-lint install-pre-commit test test-4edge test-integ test-local
+.PHONY: apidocs docs-comprehensive generate html install install-dev install-extras install-generator install-lint install-pre-commit test test-4edge test-integ test-local help
+
+help:  ## Print all targets with their descriptions
+	@grep -E '^[a-zA-Z_-]+:.*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {if (NF == 1) {printf "\033[36m%-30s\033[0m %s\n", $$1, ""} else {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}}'
+
 
 install:  ## Install the package from source
 	poetry install
@@ -16,7 +20,7 @@ install-pre-commit: install  ## Install pre-commit hooks
 	poetry run pre-commit install
 
 install-generator: install ## Install dependencies for SDK code generator
-	npm install --save remark-math@6 rehype-katex@7
+	npm install
 
 generate: install-generator  ## Generate the SDK from our public openapi spec
 	node_modules/.bin/openapi-generator-cli generate -i spec/public-api.yaml \
@@ -73,7 +77,7 @@ format: install-lint  ## Run standard python formatting
 	./code-quality/format ${LINT_PATHS}
 
 
-# Targets for sphinx documentation
+# Targets for building code.groundlight.ai and API reference documentation
 
 install-sphinx-deps: ## Only install the sphinx dependencies
 	poetry install --no-root --only sphinx-deps
@@ -86,30 +90,26 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = sphinx_docs
 BUILDDIR      = build
 
-sphinx-help:
+sphinx-help:  ## Print help for Sphinx build options (Sphinx is used to build our API reference documentation)
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-
-# Start an interactive server to test docs locally.
-# Before running this, make sure that you have installed the node modules
-# by running `node install` in the docs directory.
-develop-docs-comprehensive: docs-comprehensive
+## Before running this, make sure that you have installed the node modules
+## by running `node install` in the docs directory.
+develop-docs-comprehensive: docs-comprehensive  ## Start an interactive server to test docs locally.
 	cd docs && npm start
 
-## Builds docs comprehensively (integrating API reference docs built
-## with sphinx into the docusaurus docs).
-docs-comprehensive: apidocs
+docs-comprehensive: apidocs  ## Builds docs comprehensively (integrating API reference docs built with sphinx into the docusaurus docs).
 	rm -rf docs/static/api-reference-docs
 	rm -rf docs/build/api-reference-docs
 	mkdir docs/static/api-reference-docs
 	mv build/html/* docs/static/api-reference-docs/
 
 	cd docs && npm run build
 
-apidocs:
-	cd docs && npm install --save remark-math@6 rehype-katex@7
+apidocs:  ## Installs necessary npm packages and builds API reference documentation using Sphinx.
+	cd docs && npm install
 	poetry run make html
 
-html:
+html:  ## Builds HTML reference documentation using Sphinx.
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/docs/api-reference/_category_.json

@@ -1,5 +1,5 @@
 {
   "label": "API Reference",
-  "position": 5,
+  "position": 6,
   "collapsed": false
 }