Add support for sphinx docs and set up simple GHA (#100)

* add sphinx docs and github actions for them * linting * add pydantic models * add pydantic models * linting issues * Accept suggested change Co-authored-by: robotrapta <[email protected]> * address pr feedback * clean up * fix linting * make method static to make pylint happy * python version * final touches * test if python 3.7 and 3.8 are still supported * update sphinx-rtd-theme package * increment version requirement for autodoc-pydantic * verified tests pass with python >3.7.0 --------- Co-authored-by: robotrapta <[email protected]>
groundlight · Oct 11, 2023 · c0e66d3 · c0e66d3
1 parent e9d8f7f
commit c0e66d3
Show file tree

Hide file tree

Showing 10 changed files with 1,080 additions and 376 deletions.
diff --git a/.github/workflows/sphinx_docs.yaml b/.github/workflows/sphinx_docs.yaml
@@ -0,0 +1,35 @@
+name: Build API Reference docs using sphinx 
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main 
+
+env:
+  POETRY_VERSION: "1.6.1"
+  PYTHON_VERSION: "3.10"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: get code 
+        uses: actions/checkout@v3
+      - name: install python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: install poetry 
+        uses: snok/install-poetry@v1
+        with:
+          version: ${{ env.POETRY_VERSION }}
+
+      - name: Install dependencies 
+        run: make install-sphinx-deps
+
+      - name: Build API documentation
+        run: |
+          make apidocs
diff --git a/Makefile b/Makefile
@@ -7,6 +7,9 @@ install-extras: install  ## Install the package from source with extra dependenc
 install-lint:  ## Only install the linter dependencies
 	poetry install --only lint
 
+install-dev: ## Only install the dev dependencies
+	poetry install --only dev 
+
 install-pre-commit: install  ## Install pre-commit hooks
 	poetry run pre-commit install
 
@@ -47,3 +50,34 @@ lint: install-lint  ## Run linter to check formatting and style
 
 format: install-lint  ## Run standard python formatting
 	./code-quality/format ${LINT_PATHS}
+
+
+# Targets for sphinx documentation 
+
+install-sphinx-deps: ## Only install the sphinx dependencies
+	poetry install --no-root --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    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = sphinx_docs
+BUILDDIR      = build
+
+sphinx-help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+# The .PHONY directive tells make that `apidocs` and `html` are labels for 
+# commands. `apidocs: html` allows us to generate docs by running 
+# `make apidocs` instead. 
+.PHONY: apidocs html 
+
+apidocs: 
+	poetry run make html 
+
+html:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,15 +16,15 @@ version = "0.11.1"
 certifi = ">=2023.7.22"
 frozendict = "^2.3.2"
 pillow = "^9.0.0" # TODO: We may want to mark pillow (and numpy) as extra (https://python-poetry.org/docs/master/pyproject#extras)
-pydantic = "^1.7.4"
+pydantic = ">=2.0,<3.0.0"
 python = ">=3.7.0,<4.0"
 python-dateutil = "^2.8.2"
 requests = "^2.28.2"
 urllib3 = "^1.26.9"
 typer = "^0.9.0"
 
 [tool.poetry.group.dev.dependencies]
-datamodel-code-generator = "^0.12.1"
+datamodel-code-generator = "^0.22.1"
 pre-commit = "^2.0.0"
 pytest = "^7.0.1"
 pytest-cov = "^3.0.0"
@@ -39,6 +39,13 @@ ruff = "^0.0.261"
 toml-sort = "^0.23.0"
 types-requests = "^2.28.11.17"
 
+[tool.poetry.group.sphinx-deps.dependencies]
+python = ">=3.9.0,<4.0"
+Sphinx = {version = "7.2.6", python = ">=3.9.0,<4.0"}
+sphinx-rtd-theme = {version = "1.3.0", python = ">=3.9.0,<4.0"}
+autodoc-pydantic = {version = "2.0.1", python = ">=3.9.0,<4.0"}
+toml = "0.10.2"
+
 [tool.poetry.scripts]
 groundlight = "groundlight.cli:groundlight"
 

diff --git a/sphinx_docs/conf.py b/sphinx_docs/conf.py
@@ -0,0 +1,48 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+
+import sys
+import os
+import toml
+
+sys.path.insert(0, os.path.abspath("../src"))
+sys.path.insert(1, os.path.abspath("../generated"))
+
+
+def get_version_name() -> str:
+    pyproject_path = "../pyproject.toml"
+    with open(pyproject_path, "r") as f:
+        pyproject_deps = toml.load(f)
+
+    version = pyproject_deps["tool"]["poetry"]["version"]
+    return version
+
+
+project = "Groundlight Python SDK"
+copyright = "2023, Groundlight AI <[email protected]>"
+author = "Groundlight AI <[email protected]>"
+version = get_version_name()
+release = version
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# sphinx.ext.autodoc is a Sphinx extension that automatically documents Python modules.
+# We are using the `reStructuredText` format for docstrings instead of google style.
+extensions = ["sphinx.ext.autodoc", "sphinxcontrib.autodoc_pydantic"]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
diff --git a/sphinx_docs/index.rst b/sphinx_docs/index.rst
@@ -0,0 +1,27 @@
+
+Welcome to Groundlight Python SDK's documentation!
+==================================================
+
+For a detailed view of the source code, visit the `Groundlight SDK GitHub Repository <https://github.com/groundlight/python-sdk>`_.
+
+
+.. automodule:: groundlight.client 
+   :members:
+   :special-members: __init__
+   :exclude-members: ApiTokenError
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   models 
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/sphinx_docs/models.rst b/sphinx_docs/models.rst
@@ -0,0 +1,15 @@
+
+API Response Objects
+=====================
+
+.. autopydantic_model:: model.Detector 
+   :model-show-json: True 
+
+.. autopydantic_model:: model.ImageQuery
+   :model-show-json: True 
+
+.. autopydantic_model:: model.PaginatedDetectorList
+    :model-show-json: True 
+
+.. autopydantic_model:: model.PaginatedImageQueryList
+    :model-show-json: True