clean up docs formatting (#8)

Author: mattzcarey

examples/available_tools.py

@@ -2,6 +2,7 @@
 Get available tools from your StackOne organisation based on the account id.
 
 This example demonstrates different ways to filter and organize tools:
+
 1. Getting all available tools
 2. Filtering by vertical
 3. Using multiple patterns for cross-vertical functionality
@@ -25,15 +26,21 @@
 def get_available_tools() -> None:
     toolset = StackOneToolSet()
 
-    # First, get all tools
+    """
+    We can get all tools using the `get_tools` method.
+    """
     all_tools = toolset.get_tools()
     assert len(all_tools) > 100, "Expected at least 100 tools in total"
 
-    # Then, let's get just HRIS tools using a vertical filter
+    """
+    Then, let's get just HRIS tools using a filter. This filter accepts glob patterns.
+    """
     hris_tools = toolset.get_tools("hris_*")
     assert len(hris_tools) > 10, "Expected at least 10 HRIS tools"
 
-    # Now, let's get people-related tools across verticals
+    """
+    Filter with multiple patterns. This will return all tools that match either pattern (OR operator).
+    """
     people_tools = toolset.get_tools(
         [
             "hris_*employee*",
@@ -46,19 +53,25 @@ def get_available_tools() -> None:
             f"Tool {tool.name} doesn't contain 'employee' or 'contact'"
         )
 
-    # We can also filter by specific operations across all verticals
+    """
+    Filter by specific operations across all verticals using a glob pattern.
+    """
     upload_tools = toolset.get_tools("*upload*")
     assert len(upload_tools) > 0, "Expected at least one upload tool"
     for tool in upload_tools:
         assert "upload" in tool.name.lower(), f"Tool {tool.name} doesn't contain 'upload'"
 
-    # Get all tools except HRIS
+    """
+    The exclude pattern is also supported.
+    """
     non_hris_tools = toolset.get_tools("!hris_*")
     assert len(non_hris_tools) > 0, "Expected at least one non-HRIS tool"
     for tool in non_hris_tools:
         assert not tool.name.startswith("hris_"), f"Tool {tool.name} should not be an HRIS tool"
 
-    # Complex filtering with positive and negative patterns
+    """
+    More hectic example:
+    """
     list_tools = toolset.get_tools(
         [
             "*list*",  # Include list operations

examples/error_handling.py

@@ -20,7 +20,9 @@
 
 
 def error_handling() -> None:
-    # Example 1: Configuration error - missing API key
+    """
+    Example 1: Configuration error - missing API key
+    """
     original_api_key = os.environ.pop("STACKONE_API_KEY", None)
     try:
         try:
@@ -35,7 +37,9 @@ def error_handling() -> None:
         if original_api_key:
             os.environ["STACKONE_API_KEY"] = original_api_key
 
-    # Example 2: Invalid vertical error
+    """
+    Example 2: Invalid vertical error
+    """
     toolset = StackOneToolSet()
     try:
         # Use a non-existent vertical to trigger error
@@ -45,7 +49,9 @@ def error_handling() -> None:
     except ToolsetLoadError as e:
         assert "Error loading tools" in str(e)
 
-    # Example 3: API error - invalid request
+    """
+    Example 3: API error - invalid request
+    """
     toolset = StackOneToolSet()
     tools = toolset.get_tools("crm_*")
 

examples/file_uploads.py

@@ -22,9 +22,10 @@
 employee_id = "c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA"
 
 """
-## Resume content
+# Resume content
 
 This is a sample resume content that will be uploaded to StackOne.
+
 """
 
 resume_content = """
@@ -44,9 +45,10 @@
 
 
 """
-## Upload employee document
+# Upload employee document
 
 This function uploads a resume using the `hris_upload_employee_document` tool.
+
 """
 
 

examples/index.py

@@ -1,7 +1,7 @@
 """
 StackOne AI provides a unified interface for accessing various SaaS tools through AI-friendly APIs.
 
-## Installation
+# Installation
 
 ```bash
 # Using pip
@@ -11,7 +11,7 @@
 uv add stackone-ai
 ```
 
-## How to use these docs
+# How to use these docs
 
 All examples are complete and runnable.
 We use [uv](https://docs.astral.sh/uv/getting-started/installation/) for python dependency management.
@@ -23,13 +23,7 @@
 uv run examples/index.py
 ```
 
-## Package Usage
-"""
-
-from stackone_ai import StackOneToolSet
-
-"""
-## Authentication
+# Authentication
 
 Set the `STACKONE_API_KEY` environment variable:
 
@@ -39,12 +33,13 @@
 
 or load from a .env file:
 """
+
 from dotenv import load_dotenv
 
 load_dotenv()
 
 """
-## Account IDs
+# Account IDs
 
 StackOne uses account IDs to identify different integrations.
 See the example [stackone-account-ids.md](stackone-account-ids.md) for more details.
@@ -54,6 +49,12 @@
 
 account_id = "45072196112816593343"
 
+"""
+# Quickstart
+"""
+
+from stackone_ai import StackOneToolSet
+
 
 def quickstart():
     toolset = StackOneToolSet()
@@ -73,7 +74,7 @@ def quickstart():
     quickstart()
 
 """
-## Next Steps
+# Next Steps
 
 Check out some more documentation:
 
@@ -84,8 +85,8 @@ def quickstart():
 
 Or get started with an integration:
 
-- [OpenAI Integration](openai-integration.md)
-- [LangChain Integration](langchain-integration.md)
-- [CrewAI Integration](crewai-integration.md)
-- [LangGraph Tool Node](langgraph-tool-node.md)
+- [OpenAI](openai-integration.md)
+- [LangChain](langchain-integration.md)
+- [CrewAI](crewai-integration.md)
+- [LangGraph](langgraph-tool-node.md)
 """

examples/stackone_account_ids.py

@@ -16,16 +16,22 @@
 def stackone_account_ids():
     toolset = StackOneToolSet()
 
-    # Filter by pattern and set the account ID
+    """
+    Set the account ID whilst getting tools.
+    """
     tools = toolset.get_tools("hris_*", account_id="test_id")
 
-    # You can over write the account ID here..
+    """
+    You can over write the account ID on fetched tools.
+    """
     tools.set_account_id("a_different_id")
 
     employee_tool = tools.get_tool("hris_get_employee")
     assert employee_tool is not None
 
-    # You can even set the account ID on a per-tool basis
+    """
+    You can even set the account ID on a per-tool basis.
+    """
     employee_tool.set_account_id("again_another_id")
     assert employee_tool.get_account_id() == "again_another_id"