fix: docs formatting (#6)

Author: mattzcarey

Makefile

@@ -19,3 +19,11 @@ test-examples:
 
 mypy:
 	uv run mypy stackone_ai
+
+docs-serve:
+	uv run scripts/build_docs.py
+	uv run mkdocs serve
+
+docs-build:
+	uv run scripts/build_docs.py
+	uv run mkdocs build

examples/available_tools.py

@@ -8,7 +8,7 @@
 4. Filtering by specific operations
 5. Combining multiple operation patterns
 
-# TODO: experimental - get_available_tools(account_id="your_account_id")
+TODO: experimental - get_available_tools(account_id="your_account_id")
 
 ```bash
 uv run examples/available_tools.py

examples/file_uploads.py

@@ -1,6 +1,6 @@
 """
-Example demonstrating file upload functionality with StackOne.
-Shows how to upload an employee document using the HRIS integration.
+Example demonstrating file upload functionality using StackOne.
+Shows how to upload an employee document using an HRIS integration.
 
 This example is runnable with the following command:
 ```bash
@@ -21,11 +21,13 @@
 account_id = "45072196112816593343"
 employee_id = "c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA"
 
+"""
+## Resume content
 
-def upload_employee_document() -> None:
-    """Demonstrate uploading an employee document using StackOne."""
-    with tempfile.TemporaryDirectory() as temp_dir:
-        resume_content = """
+This is a sample resume content that will be uploaded to StackOne.
+"""
+
+resume_content = """
         JOHN DOE
         Software Engineer
 
@@ -38,9 +40,18 @@ def upload_employee_document() -> None:
         EDUCATION
         BS Computer Science
         University of Technology
-        2016-2020
-        """
+        2016-2020 """
+
 
+"""
+## Upload employee document
+
+This function uploads a resume using the `hris_upload_employee_document` tool.
+"""
+
+
+def upload_employee_document() -> None:
+    with tempfile.TemporaryDirectory() as temp_dir:
         resume_file = Path(temp_dir) / "resume.pdf"
         resume_file.write_text(resume_content)
 

examples/index.py

@@ -1,52 +1,58 @@
 """
-# Getting Started
-
 StackOne AI provides a unified interface for accessing various SaaS tools through AI-friendly APIs.
 
 ## Installation
 
 ```bash
+# Using pip
 pip install stackone-ai
-```
 
+# Using uv
+uv add stackone-ai
+```
 
-## Quick Start
+## How to use these docs
 
-Here's a simple example. All examples are complete and runnable.
+All examples are complete and runnable.
+We use [uv](https://docs.astral.sh/uv/getting-started/installation/) for python dependency management.
 
-You can even run the example directly from the command line:
+To run this example, install the dependencies (one-time setup) and run the script:
 
 ```bash
+uv sync --all-extras
 uv run examples/index.py
 ```
-"""
 
-from dotenv import load_dotenv
+## Package Usage
+"""
 
 from stackone_ai import StackOneToolSet
 
 """
-## Authenticate with StackOne
+## Authentication
+
+Set the `STACKONE_API_KEY` environment variable:
 
 ```bash
 export STACKONE_API_KEY=<your-api-key>
 ```
 
 or load from a .env file:
 """
+from dotenv import load_dotenv
 
 load_dotenv()
 
 """
 ## Account IDs
 
 StackOne uses account IDs to identify different integrations.
-See the example [stackone_account_ids.py](stackone_account_ids.py) for more details.
-This example will hardcode the account ID.
+See the example [stackone-account-ids.md](stackone-account-ids.md) for more details.
+
+This example will hardcode the account ID:
 """
 
 account_id = "45072196112816593343"
-employee_id = "c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA"
 
 
 def quickstart():
@@ -56,11 +62,11 @@ def quickstart():
     tools = toolset.get_tools("hris_*", account_id=account_id)
 
     # Use a specific tool
-    employee_tool = tools.get_tool("hris_get_employee")
+    employee_tool = tools.get_tool("hris_list_employees")
     assert employee_tool is not None
 
-    employee = employee_tool.execute({"id": employee_id})
-    assert employee is not None
+    employees = employee_tool.execute()
+    assert employees is not None
 
 
 if __name__ == "__main__":
@@ -71,8 +77,8 @@ def quickstart():
 
 Check out some more documentation:
 
-- [Error Handling](error-handling.md)
 - [StackOne Account IDs](stackone-account-ids.md)
+- [Error Handling](error-handling.md)
 - [Available Tools](available-tools.md)
 - [File Uploads](file-uploads.md)
 

mkdocs.yml

@@ -6,48 +6,46 @@ repo_name: StackOneHQ/stackone-ai-python
 docs_dir: .docs
 
 theme:
-  name: material
-  palette:
-    - media: "(prefers-color-scheme: light)"
-      scheme: default
-      primary: black
-      accent: teal
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-    - media: "(prefers-color-scheme: dark)"
-      scheme: slate
-      primary: teal
-      accent: black
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
+  name: terminal
+  palette: default
   features:
-    - navigation.instant
-    - navigation.tracking
-    - navigation.sections
-    - navigation.expand
-    - navigation.indexes
-    - toc.follow
-    - content.code.copy
+    - footer.prev_next
+    - navigation.side.indexes
+    - navigation.side.toc.hide
+    - revision.date
+    - revision.history
+    - style.links.underline.hide
 
 markdown_extensions:
-  - pymdownx.highlight:
-      anchor_linenums: true
-  - pymdownx.inlinehilite
-  - pymdownx.snippets
-  - pymdownx.superfences
-  - admonition
-  - pymdownx.details
   - attr_list
+  - def_list
+  - footnotes
   - md_in_html
+  - meta
+  - toc:
+      permalink: "#"
+      permalink_title: Anchor link to this section for reference
+  - pymdownx.caret
+  - pymdownx.mark
+  - pymdownx.tilde
+  - pymdownx.snippets:
+      base_path:
+        - .docs
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      use_pygments: true
+      pygments_style: lovelace
+      noclasses: true
+  - pymdownx.inlinehilite
 
 nav:
   - Home: index.md
-  - Examples:
-      - OpenAI Integration: openai-integration.md
-      - CrewAI Integration: crewai-integration.md
-      - LangChain Integration: langchain-integration.md
+  - Usage:
       - StackOne Account IDs: stackone-account-ids.md
-  - Error Handling: error-handling.md
-  - File Uploads: file-uploads.md
+      - Error Handling: error-handling.md
+      - Available Tools: available-tools.md
+      - File Uploads: file-uploads.md
+  - Integrations:
+      - OpenAI: openai-integration.md
+      - CrewAI: crewai-integration.md
+      - LangChain: langchain-integration.md

pyproject.toml

@@ -36,11 +36,10 @@ examples = [
     "python-dotenv>=1.0.1",
 ]
 docs = [
-    "mkdocs-material>=9.6.4",
-]
-pymdown-extensions = [
-    "mkdocs-material>=9.6.4",
-]
+    "mkdocs-terminal>=4.7.0",
+    "pygments>=2.12",
+    "pymdown-extensions"
+] 
 
 [dependency-groups]
 dev = [
@@ -66,7 +65,7 @@ markers = [
 "bin/**.py" = ["T201", "T203"]
 "scripts/**.py" = ["T201", "T203"]
 "tests/**.py" = ["T201", "T203"]
-"examples/**.py" = ["T201", "T203", "E501", "F841"]
+"examples/**.py" = ["T201", "T203", "E501", "F841", "E402"]
 
 [tool.ruff]
 line-length = 110

scripts/build_docs.py

@@ -17,11 +17,13 @@ def convert_file_to_markdown(py_file: Path) -> str:
     output = [f"# {title}\n"]
 
     # Find all docstrings and their positions
-    docstring_pattern = r'"""(.*?)"""'
+    # Match docstrings that start and end on their own lines
+    docstring_pattern = r'(\n|\A)\s*"""(.*?)"""(\s*\n|\Z)'
     current_pos = 0
 
     for match in re.finditer(docstring_pattern, content, re.DOTALL):
         start, end = match.span()
+        docstring_content = match.group(2).strip()  # The actual docstring content is in group 2
 
         # If there's code before this docstring, wrap it
         if current_pos < start:
@@ -32,7 +34,7 @@ def convert_file_to_markdown(py_file: Path) -> str:
                 output.append("```\n")
 
         # Add the docstring content as markdown
-        output.append(match.group(1).strip())
+        output.append(docstring_content)
         current_pos = end
 
     # Add any remaining code