Restore missing SDK client docs in API reference (#434)

## Summary

The API reference docs page (`/api-reference-docs/`) was missing all
content for `Groundlight` and `ExperimentalApi` -- only the API response
object models were rendering.

**Root cause:** PR #413 ("Migrate Edge Configuration to SDK") introduced
`groundlight/edge/config.py`, which does `import yaml`. PR #419 ("SDK
Configures Edge") then wired this into the import chain accessible from
`groundlight/__init__.py`. When sphinx builds the docs, it installs only
the `sphinx-deps` dependency group (via `poetry install --no-root --only
sphinx-deps`). Since `pyyaml` was not in that group, sphinx's `autodoc`
failed to import `groundlight.Groundlight` and
`groundlight.ExperimentalApi` with `No module named 'yaml'`. Sphinx
treated this as a non-fatal warning and silently omitted those sections
from the built docs. The docs have been broken since the April 7 deploy.

## Changes

- **`pyproject.toml`**: Removed duplicate dependencies from
`sphinx-deps` that were already in the main deps group (`pillow`,
`pydantic`, `python-dateutil`). The `sphinx-deps` group now only
contains sphinx-specific packages.
- **`Makefile`**: Changed `install-sphinx-deps` to install both the
`main` and `sphinx-deps` groups (`--only main --only sphinx-deps`), so
sphinx always has access to whatever the SDK imports. Also added `-W` to
`SPHINXOPTS` so sphinx treats warnings as errors -- CI will now fail
immediately if autodoc can't import a documented class, preventing this
class of silent breakage in the future.
- **`sphinx_docs/conf.py`**: Removed `html_static_path` entry
referencing a non-existent `_static` directory.
- **`sphinx_docs/models.rst`**: Added `EdgeEndpointApi` as a documented
class under a new "Edge Endpoint API" section.
- **`src/groundlight/edge/api.py`**: Improved `EdgeEndpointApi` class
docstring to explain how it's accessed (`gl.edge`).
- **`src/groundlight/client.py`** and
**`src/groundlight/experimental_api.py`**: Fixed pre-existing RST
docstring formatting issues (indentation errors, missing `::` on code
block headers, trailing underscores interpreted as hyperlink references)
that `-W` surfaced.

---------

Co-authored-by: Tim Huff <thuff@axon.com>

Author: timmarkhuff

Makefile

@@ -79,13 +79,13 @@ format: install-lint  ## Run standard python formatting
 
 # 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
+install-sphinx-deps: ## Install the main dependencies and sphinx-specific dependencies
+	poetry install --no-root --only main --only sphinx-deps
 
 # The following is auto-generated by sphinx-quickstart:
 # To test out doc changes locally, run
 # poetry run make html && open build/html/index.html
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = sphinx_docs
 BUILDDIR      = build

generated/groundlight_openapi_client/api/image_queries_api.py

@@ -425,7 +425,7 @@ def list_image_queries(self, **kwargs):
 
     def submit_image_query(self, detector_id, **kwargs):
         """submit_image_query  # noqa: E501
-
+        
          Submit an image query against a detector.  You must use `\"Content-Type: image/jpeg\"` or similar (image/png, image/webp, etc) for the image data. For example: ```Bash $ curl https://api.groundlight.ai/device-api/v1/image-queries?detector_id=det_abc123 \\     --header \"Content-Type: image/jpeg\" \\     --data-binary @path/to/filename.jpeg ```   # noqa: E501
         This method makes a synchronous HTTP request by default. To make an
         asynchronous HTTP request, please pass async_req=True

pyproject.toml

@@ -43,13 +43,8 @@ types-PyYAML = "^6.0.0"
 types-requests = "^2.28.11.17"
 
 [tool.poetry.group.sphinx-deps.dependencies]
-# These are extra / stricter dependencies required to build the API reference docs
 Sphinx = {version = "^7.2.6", python = ">=3.9,<4.0"}
 autodoc-pydantic = {version = "^2.0.1", python = ">=3.9,<4.0"}
-pillow = "^11.0.0"
-pydantic = "^2.0.0"
-python = ">=3.9,<4.0"
-python-dateutil = "^2.8.2"
 sphinx-rtd-theme = {version = "^1.3.0", python = ">=3.9,<4.0"}
 toml = "^0.10.2"
 

sphinx_docs/conf.py

@@ -51,4 +51,3 @@ def get_version_name() -> str:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
-html_static_path = ["_static"]

sphinx_docs/models.rst

@@ -9,6 +9,12 @@ SDK Client
    :members:
    :special-members: __init__
 
+Edge Endpoint API
+=====================
+
+.. autoclass:: groundlight.edge.api.EdgeEndpointApi
+   :members:
+
 API Response Objects
 =====================
 

src/groundlight/client.py

@@ -434,6 +434,7 @@ def create_detector(  # noqa: PLR0913
                 group_name="parking-monitoring",
                 patience_time=60.0
             )
+
         :param name: A short, descriptive name for the detector. This name should be unique within your account
                     and help identify the detector's purpose.
         :param query: The question that the detector will answer about images. For binary classification,
@@ -609,7 +610,7 @@ def get_image_query(self, id: str) -> ImageQuery:  # pylint: disable=redefined-b
         Get an ImageQuery by its ID. This is useful for retrieving the status and results of a
         previously submitted query.
 
-        **Example Usage:**
+        **Example usage**::
 
             gl = Groundlight()
 
@@ -753,12 +754,14 @@ def submit_image_query(  # noqa: PLR0913 # pylint: disable=too-many-arguments, t
 
         :param detector: the Detector object, or string id of a detector like `det_12345`
         :param image: The image, in several possible formats:
+
             - filename (string) of a jpeg file
             - byte array or BytesIO or BufferedReader with jpeg bytes
             - numpy array with values 0-255 and dimensions (H,W,3) in BGR order
-                (Note OpenCV uses BGR not RGB. `img[:, :, ::-1]` will reverse the channels)
+              (Note OpenCV uses BGR not RGB. `img[:, :, ::-1]` will reverse the channels)
             - PIL Image: Any binary format must be JPEG-encoded already.
-                Any pixel format will get converted to JPEG at high quality before sending to service.
+              Any pixel format will get converted to JPEG at high quality before sending to service.
+
         :param wait: How long to poll (in seconds) for a confident answer. This is a client-side timeout.
             Default is 30.0. Set to 0 for async operation.
         :param patience_time: How long to wait (in seconds) for a confident answer for this image query.
@@ -874,11 +877,13 @@ def ask_confident(  # noqa: PLR0913 # pylint: disable=too-many-arguments
 
         :param detector: the Detector object, or string id of a detector like `det_12345`
         :param image: The image, in several possible formats:
+
           - filename (string) of a jpeg file
           - byte array or BytesIO or BufferedReader with jpeg bytes
           - numpy array with values 0-255 and dimensions (H,W,3) in BGR order
             (Note OpenCV uses BGR not RGB. `img[:, :, ::-1]` will reverse the channels)
           - PIL Image
+
           Any binary format must be JPEG-encoded already.  Any pixel format will get
           converted to JPEG at high quality before sending to service.
         :param confidence_threshold: The confidence threshold to wait for.
@@ -944,11 +949,13 @@ def ask_ml(  # noqa: PLR0913 # pylint: disable=too-many-arguments, too-many-loca
 
         :param detector: the Detector object, or string id of a detector like `det_12345`
         :param image: The image, in several possible formats:
+
           - filename (string) of a jpeg file
           - byte array or BytesIO or BufferedReader with jpeg bytes
           - numpy array with values 0-255 and dimensions (H,W,3) in BGR order
             (Note OpenCV uses BGR not RGB. `img[:, :, ::-1]` will reverse the channels)
           - PIL Image
+
           Any binary format must be JPEG-encoded already.  Any pixel format will get
           converted to JPEG at high quality before sending to service.
         :param wait: How long to wait (in seconds) for any ML prediction.
@@ -1032,12 +1039,14 @@ def ask_async(  # noqa: PLR0913 # pylint: disable=too-many-arguments
 
         :param detector: the Detector object, or string id of a detector like `det_12345`
         :param image: The image, in several possible formats:
+
             - filename (string) of a jpeg file
             - byte array or BytesIO or BufferedReader with jpeg bytes
             - numpy array with values 0-255 and dimensions (H,W,3) in BGR order
               (Note OpenCV uses BGR not RGB. `img[:, :, ::-1]` will reverse the channels)
             - PIL Image: Any binary format must be JPEG-encoded already.
               Any pixel format will get converted to JPEG at high quality before sending to service.
+
         :param patience_time: How long to wait (in seconds) for a confident answer for this image query.
             The longer the patience_time, the more likely Groundlight will arrive at a
             confident answer. This is a soft server-side timeout. If not set, use the
@@ -1236,7 +1245,7 @@ def add_label(
         Examples for other answer modes can be found in the documentation for each of the modes.
 
         :param image_query: Either an ImageQuery object (returned from methods like
-                          `ask_ml`) or an image query ID string starting with "iq_".
+                          `ask_ml`) or an image query ID string starting with ``iq_``.
 
         :param label: The label value to assign, typically "YES" or "NO" for binary
                      classification detectors. For multi-class detectors, use one of
@@ -1442,7 +1451,7 @@ def update_detector_status(self, detector: Union[str, Detector], enabled: bool)
             # Using a detector ID string directly
             gl.update_detector_status("det_abc123", enabled=True)  # Enable the detector
 
-        :param detector: Either a Detector object or a detector ID string starting with "det_".
+        :param detector: Either a Detector object or a detector ID string starting with ``det_``.
                        The detector whose status should be updated.
         :param enabled: Boolean indicating whether the detector should be enabled (True) or
                        disabled (False). When disabled, the detector will not process new queries.
@@ -1478,7 +1487,7 @@ def update_detector_escalation_type(self, detector: Union[str, Detector], escala
             # Re-enable standard human labeling
             gl.update_detector_escalation_type("det_abc123", "STANDARD")
 
-        :param detector: Either a Detector object or a detector ID string starting with "det_".
+        :param detector: Either a Detector object or a detector ID string starting with ``det_``.
                        The detector whose escalation type should be updated.
         :param escalation_type: The new escalation type setting. Must be one of:
                               - "STANDARD": Allow human labeling for low-confidence queries
@@ -1516,7 +1525,7 @@ def delete_detector(self, detector: Union[str, Detector]) -> None:
             # Using a detector ID string directly
             gl.delete_detector("det_abc123")
 
-        :param detector: Either a Detector object or a detector ID string starting with "det_".
+        :param detector: Either a Detector object or a detector ID string starting with ``det_``.
                        The detector to delete.
 
         :return: None

src/groundlight/edge/api.py

@@ -16,6 +16,12 @@ class EdgeEndpointApi:
     """
     Namespace for operations that are specific to the Edge Endpoint,
     such as setting and getting the EdgeEndpoint configuration.
+
+    Currently only available through :class:`~groundlight.ExperimentalApi`. Accessed via the
+    ``edge`` attribute::
+
+        gl = ExperimentalApi()
+        gl.edge.set_config(config)
     """
 
     def __init__(self, client) -> None:

src/groundlight/experimental_api.py

@@ -183,7 +183,7 @@ def reset_detector(self, detector: Union[str, Detector]) -> None:
             # Using a detector ID string directly
             gl.reset_detector("det_abc123")
 
-        :param detector: Either a Detector object or a detector ID string starting with "det_".
+        :param detector: Either a Detector object or a detector ID string starting with ``det_``.
                        The detector whose data should be reset.
 
         :return: None
@@ -207,7 +207,7 @@ def update_detector_name(self, detector: Union[str, Detector], name: str) -> Non
             # Using a detector ID string directly
             gl.update_detector_name("det_abc123", "new_detector_name")
 
-        :param detector: Either a Detector object or a detector ID string starting with "det_".
+        :param detector: Either a Detector object or a detector ID string starting with ``det_``.
                        The detector whose name should be updated.
         :param name: The new name to assign to the detector