feat: docs site

Author: Matt Carey

.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Install docs dependencies
+        run: uv pip install -r requirements-docs.txt
+
+      - name: Build documentation
+        run: |
+          uv run scripts/build_docs.py
+          uv run mkdocs build
+
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

.gitignore

@@ -7,3 +7,7 @@
 __pycache__
 
 .DS_Store
+
+# Documentation build
+.docs/
+site/

.pre-commit-config.yaml

@@ -1,16 +1,16 @@
 repos:
--   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.3.0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
     hooks:
-    -   id: ruff
-        args: [ --fix ]
-    -   id: ruff-format
-        
--   repo: https://github.com/pre-commit/mirrors-mypy
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.8.0
     hooks:
-    -   id: mypy
+      - id: mypy
         files: ^packages/stackone-ai/stackone_ai/
-        additional_dependencies: 
+        additional_dependencies:
           - types-requests
-          - types-PyYAML 
+          - types-PyYAML

examples/api_reference.py

@@ -0,0 +1,118 @@
+"""
+## StackOneToolSet
+
+The main class for accessing StackOne tools.
+
+### Constructor
+
+```python
+StackOneToolSet(
+    api_key: str | None = None,
+    account_id: str | None = None
+)
+```
+
+**Parameters:**
+- `api_key`: Optional API key. If not provided, uses `STACKONE_API_KEY` env variable
+- `account_id`: Optional account ID. If not provided, uses `STACKONE_ACCOUNT_ID` env variable
+
+### Methods
+
+#### get_tools
+
+```python
+def get_tools(
+    vertical: str,
+    account_id: str | None = None
+) -> Tools
+```
+
+Get tools for a specific vertical.
+
+**Parameters:**
+- `vertical`: The vertical to get tools for (e.g. "hris", "crm")
+- `account_id`: Optional account ID override. If not provided, uses the one from initialization
+
+**Returns:**
+- `Tools` instance containing available tools
+
+## Tools
+
+Container for Tool instances.
+
+### Methods
+
+#### get_tool
+
+```python
+def get_tool(name: str) -> BaseTool | None
+```
+
+Get a tool by its name.
+
+**Parameters:**
+- `name`: Name of the tool to get
+
+**Returns:**
+- `BaseTool` instance if found, None otherwise
+
+#### to_openai
+
+```python
+def to_openai() -> list[dict]
+```
+
+Convert all tools to OpenAI function format.
+
+**Returns:**
+- List of tools in OpenAI function format
+
+## BaseTool
+
+Base class for individual tools.
+
+### Methods
+
+#### execute
+
+```python
+def execute(arguments: str | dict) -> dict[str, Any]
+```
+
+Execute the tool with the given parameters.
+
+**Parameters:**
+- `arguments`: Either a JSON string or dict of arguments
+
+**Returns:**
+- Tool execution results
+
+#### to_openai_function
+
+```python
+def to_openai_function() -> dict
+```
+
+Convert this tool to OpenAI's function format.
+
+**Returns:**
+- Tool definition in OpenAI function format
+"""
+
+# Example usage of the API
+from stackone_ai import StackOneToolSet
+
+# Initialize with environment variables
+toolset = StackOneToolSet()
+
+# Get tools for HRIS vertical
+tools = toolset.get_tools(vertical="hris")
+
+# Get a specific tool
+employee_tool = tools.get_tool("get_employee")
+if employee_tool:
+    # Execute the tool
+    result = employee_tool.execute({"id": "employee123"})
+
+    # Convert to OpenAI format
+    openai_function = employee_tool.to_openai_function()

examples/basic_tool_usage.py

@@ -1,3 +1,11 @@
+"""
+This example shows how to use StackOne tools.
+
+## Requirements
+- STACKONE_API_KEY
+- STACKONE_ACCOUNT_ID
+"""
+
 import os
 
 from dotenv import load_dotenv
@@ -17,9 +25,19 @@ def main():
     # Initialize the toolset with your API key
     toolset = StackOneToolSet(api_key=api_key)
 
-    # Get tools for a specific vertical (e.g. "hris")
+    """
+    ## Using Tools
+
+    Once initialized, you can get tools for specific verticals:
+    """
+
+    # Get HRIS tools
     tools = toolset.get_tools(vertical="hris", account_id=account_id)
 
+    """
+    Then use specific tools by name:
+    """
+
     # Example: Get an employee by ID
     try:
         # The tool name comes from the x-speakeasy-name-override in the OpenAPI spec

examples/getting_started.py

@@ -0,0 +1,61 @@
+"""
+# Getting Started with StackOne AI
+
+StackOne AI provides a unified interface for accessing various SaaS tools through AI-friendly APIs.
+
+## Installation
+
+Install StackOne AI using pip:
+
+```bash
+pip install stackone-ai
+```
+
+
+## Quick Start
+
+Here's a simple example to get you started:
+"""
+
+import os
+
+from dotenv import load_dotenv
+from stackone_ai import StackOneToolSet
+
+
+def quickstart():
+    # Load environment variables
+    load_dotenv()
+
+    api_key = os.getenv("STACKONE_API_KEY")
+    account_id = os.getenv("STACKONE_ACCOUNT_ID")
+
+    # Initialize the toolset
+    toolset = StackOneToolSet(api_key=api_key)
+
+    # Get HRIS tools
+    tools = toolset.get_tools(vertical="hris", account_id=account_id)
+
+    # Use a specific tool
+    employee_tool = tools.get_tool("get_employee")
+    if employee_tool:
+        employee = employee_tool.execute({"id": "employee_id"})
+        print(employee)
+
+
+"""
+## Authentication
+
+StackOne AI requires two key pieces of information:
+- `STACKONE_API_KEY`: Your API key from StackOne
+- `STACKONE_ACCOUNT_ID`: Your account ID
+
+You can set these as environment variables or pass them directly to the StackOneToolSet constructor.
+
+## Next Steps
+
+Check out some examples:
+- [Basic Tool Usage](basic-tool-usage.md)
+- [Error Handling](error-handling.md)
+- [OpenAI Integration](openai-integration.md)
+"""

examples/openai_tools_example.py examples/openai_integration.pyexamples/openai_tools_example.py renamed to examples/openai_integration.py

@@ -0,0 +1,51 @@
+site_name: StackOne AI SDK
+site_url: https://stackonehq.github.io/stackone-ai-python
+repo_url: https://github.com/StackOneHQ/stackone-ai-python
+repo_name: StackOneHQ/stackone-ai-python
+
+docs_dir: .docs
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - navigation.expand
+    - navigation.indexes
+    - toc.follow
+    - content.code.copy
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - md_in_html
+
+nav:
+  - Home: getting-started.md
+  - Examples:
+      - Basic Tool Usage: basic-tool-usage.md
+      - Error Handling: error-handling.md
+      - OpenAI Integration: openai-integration.md
+  - API Reference: api-reference.md