docs: updated docs to reflect new changes to tutorial scripts

senthurayyappan · senthurayyappan · commit b754731ef91c · 2025-02-17T23:11:25.000-05:00
diff --git a/docs/developing.md b/docs/developing.md
@@ -1,31 +1,91 @@
-# Sequence Diagram
+# Developer Documentation
 
-<body>
-    <pre class="mermaid">
-    sequenceDiagram
-        participant User as User
-        participant Client as onshape-robotics-toolkit.client
-        participant Onshape as Onshape Server
-        participant Robot as onshape-robotics-toolkit.robot
+This document provides an overview of how the onshape-robotics-toolkit library works internally and how different components interact with each other.
 
-        User->>Client: Initialize Client with API Keys
-        Client->>Onshape: Authenticate with Access Key & Secret Key
-        Onshape-->>Client: Return Authentication Token
+## Architecture Overview
 
-        User->>Client: Request Document Information (e.g., document URL)
-        Client->>Onshape: Send GET request for Document Details
-        Onshape-->>Client: Return Document Metadata (JSON)
-        Client-->>User: Deliver Document Metadata
+The library is organized into several key components:
+- **Client**: Handles all communication with the Onshape API
+- **Robot**: Manages the robot model creation and URDF export
+- **Assembly**: Represents the CAD assembly structure
+- **Utilities**: Helper functions for various operations
 
-        User->>Client: Request CAD Assembly
-        Client->>Onshape: Send GET request for Assembly Details
-        Onshape-->>Client: Return Assembly Data (JSON)
-        Client-->>User: Deliver Assembly Data
+## Workflow Overview
 
-        User->>Robot: Initiate URDF Export Workflow
-        Robot-->>Onshape: Parse Assembly Data for URDF
-        Robot-->>User: Deliver Robot model (URDF)
+### 1. Authentication and Connection
+The library first establishes a secure connection with Onshape:
+- Users provide API credentials (access key and secret key)
+- The Client component handles authentication and maintains the session
+- All subsequent API requests use this authenticated session
 
-        User->>User: Use URDF for Simulation or Control
+### 2. Document Access
+Once authenticated:
+- The library can access Onshape documents using either URLs or direct document IDs
+- Document metadata is retrieved to verify access and get necessary identifiers
+- Assembly information is cached to minimize API calls
 
-</body>
+### 3. Assembly Processing
+The assembly processing workflow:
+1. Retrieves the full assembly structure from Onshape
+2. Parses the hierarchical relationship between components
+3. Identifies joints, mate connectors, and other relevant features
+4. Creates an internal representation of the robot structure
+
+### 4. URDF Generation
+The URDF export process:
+1. Analyzes the assembly structure
+2. Maps Onshape constraints to URDF joints
+3. Exports geometry in specified formats
+4. Generates a complete URDF file with proper kinematics
+
+## Sequence Diagram
+
+The following sequence diagram illustrates the main interactions between components:
+
+<pre class="mermaid">
+sequenceDiagram
+    participant User as User
+    participant Client as onshape-robotics-toolkit.client
+    participant Onshape as Onshape Server
+    participant Robot as onshape-robotics-toolkit.robot
+
+    User->>Client: Initialize Client with API Keys
+    Client->>Onshape: Authenticate with Access Key & Secret Key
+    Onshape-->>Client: Return Authentication Token
+
+    User->>Client: Request Document Information (e.g., document URL)
+    Client->>Onshape: Send GET request for Document Details
+    Onshape-->>Client: Return Document Metadata (JSON)
+    Client-->>User: Deliver Document Metadata
+
+    User->>Client: Request CAD Assembly
+    Client->>Onshape: Send GET request for Assembly Details
+    Onshape-->>Client: Return Assembly Data (JSON)
+    Client-->>User: Deliver Assembly Data
+
+    User->>Robot: Initiate URDF Export Workflow
+    Robot-->>Onshape: Parse Assembly Data for URDF
+    Robot-->>User: Deliver Robot model (URDF)
+
+    User->>User: Use URDF for Simulation or Control
+</pre>
+
+## Key Classes and Their Roles
+
+### Client Class
+- Manages API authentication
+- Handles all HTTP requests to Onshape
+- Implements rate limiting and error handling
+- Caches responses when appropriate
+
+### Robot Class
+- Represents the complete robot model
+- Manages the conversion from CAD assembly to URDF
+- Handles coordinate transformations
+- Provides visualization utilities
+
+### Assembly Class
+- Represents the CAD assembly structure
+- Maintains parent-child relationships
+- Tracks mate connections and constraints
+- Manages geometric transformations
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -57,8 +57,8 @@ Access to the Onshape API requires authentication using API keys. Follow these s
 Create a `.env` file in the root directory of your project to securely store your API keys:
 
 ```plaintext
-ACCESS_KEY = <your_access_key>
-SECRET_KEY = <your_secret_key>
+ONSHAPE_ACCESS_KEY = <your_access_key>
+ONSHAPE_SECRET_KEY = <your_secret_key>
 ```
 
 The `onshape-robotics-toolkit` library will automatically read these keys to authenticate your requests.
diff --git a/docs/tutorials/edit.md b/docs/tutorials/edit.md
@@ -1,4 +1,6 @@
-In this tutorial, we’ll explore how to edit an Onshape CAD assembly by modifying its variables in the Variable Studio and exporting the resulting assembly to a URDF file using the `onshape-robotics-toolkit` Python library.
+In this tutorial, we'll explore how to edit an Onshape CAD assembly by modifying its variables in the Variable Studio and exporting the resulting assembly to a URDF file using the `onshape-robotics-toolkit` Python library.
+
+> 💡 The complete source code for this tutorial can be found in [`examples/edit/main.py`](../../examples/edit/main.py).
 
 <img src="bike-header.gif" alt="Bike Header" style="width: 100%;">
 
@@ -13,7 +15,7 @@ Before you begin, make sure you have:
   pip install onshape-robotics-toolkit
   ```
 - **API Keys**: Set up your Onshape API keys in a `.env` file as outlined in the [Getting Started](../getting-started.md) guide.
-- **Access to the Onshape Document**: Use a CAD document with a Variable Studio. For this tutorial, we’ll use the following example:
+- **Access to the Onshape Document**: Use a CAD document with a Variable Studio. For this tutorial, we'll use the following example:
   <a href="https://cad.onshape.com/documents/a1c1addf75444f54b504f25c/w/0d17b8ebb2a4c76be9fff3c7/e/a86aaf34d2f4353288df8812" target="_blank">Example CAD Document</a>.
 
 ---
@@ -25,11 +27,16 @@ Before you begin, make sure you have:
 Set up the Onshape API client for authentication and interaction:
 
 ```python
-import onshape_robotics_toolkit as osa
+from onshape_robotics_toolkit.connect import Client
+from onshape_robotics_toolkit.log import LOGGER, LogLevel
+
+# Set up logging
+LOGGER.set_file_name("edit.log")
+LOGGER.set_stream_level(LogLevel.INFO)
 
 # Initialize the client
-client = osa.Client(
-    env="./.env"
+client = Client(
+    env=".env"
 )
 ```
 
@@ -40,7 +47,9 @@ client = osa.Client(
 Use the CAD document URL to create a `Document` object and fetch its variables:
 
 ```python
-doc = osa.Document.from_url(
+from onshape_robotics_toolkit.models.document import Document
+
+doc = Document.from_url(
     url="https://cad.onshape.com/documents/a1c1addf75444f54b504f25c/w/0d17b8ebb2a4c76be9fff3c7/e/a86aaf34d2f4353288df8812"
 )
 
@@ -56,7 +65,7 @@ variables = client.get_variables(doc.did, doc.wid, elements["variables"].id)
 Edit the variables to adjust the CAD assembly dimensions. For example, modify the wheel diameter, wheel thickness, and fork angle:
 
 ```python
-variables["wheelDiameter"].expression = "300 mm"
+variables["wheelDiameter"].expression = "180 mm"
 variables["wheelThickness"].expression = "71 mm"
 variables["forkAngle"].expression = "20 deg"
 
@@ -83,13 +92,12 @@ from onshape_robotics_toolkit.parse import (
 assembly = client.get_assembly(doc.did, doc.wtype, doc.wid, elements["assembly"].id)
 
 # Extract components
-instances, occurrences, id_to_name_map = get_instances(assemblymax_depth=1)
+instances, occurrences, id_to_name_map = get_instances(assembly, max_depth=1)
 
 subassemblies, rigid_subassemblies = get_subassemblies(assembly, client, instances)
 parts = get_parts(assembly, rigid_subassemblies, client, instances)
 
 mates, relations = get_mates_and_relations(assembly, subassemblies, rigid_subassemblies, id_to_name_map, parts)
-
 ```
 
 ---
@@ -100,13 +108,12 @@ Generate a graph visualization of the assembly structure:
 
 ```python
 from onshape_robotics_toolkit.graph import create_graph
-from onshape_robotics_toolkit.urdf import get_robot
-from onshape_robotics_toolkit.models.robot import Robot
+from onshape_robotics_toolkit.robot import get_robot
 
-# Create and save the assembly graph
+# Create and visualize the assembly graph
 graph, root_node = create_graph(occurrences=occurrences, instances=instances, parts=parts, mates=mates)
-
 robot = get_robot(assembly, graph, root_node, parts, mates, relations, client, "test")
+robot.show_tree()
 robot.show_graph("bike.png")
 ```
 
@@ -121,7 +128,7 @@ This will save an image of the assembly graph (`bike.png`) in your current worki
 Convert the robot class into a URDF file for robotics applications:
 
 ```python
-robot.save("bike.urdf")
+robot.save()
 ```
 
 <img src="bike-urdf.gif" alt="Bike URDF" style="width: 100%;">
diff --git a/docs/tutorials/export.md b/docs/tutorials/export.md
@@ -15,7 +15,7 @@ Before you begin, ensure the following:
   pip install onshape-robotics-toolkit
   ```
 - **API Keys**: Set up your Onshape API keys in a `.env` file. Refer to the [Getting Started](../getting-started.md) guide if needed.
-- **Document URL**: Have the URL of the Onshape assembly you want to export. For this example, we’ll use a quadruped robot assembly.
+- **Document URL**: Have the URL of the Onshape assembly you want to export. For this example, we'll use a quadruped robot assembly.
 
 ---
 
@@ -32,7 +32,7 @@ from onshape_robotics_toolkit.log import LOGGER, LogLevel
 LOGGER.set_file_name("quadruped.log")
 LOGGER.set_stream_level(LogLevel.INFO)
 
-client = Client(env="./.env")
+client = Client(env=".env")
 ```
 
 The logger will save logs to `quadruped.log` and display logs at the `INFO` level in the console.
@@ -73,9 +73,9 @@ This will save the assembly details into a file named `quadruped.json` in the cu
 
 ---
 
-### Step 4: Visualize the Assembly Graph
+### Step 4: Visualize the Assembly Graph (Optional)
 
-Generate and save a graphical representation of the assembly’s structure:
+Generate and save a graphical representation of the assembly's structure:
 
 ```python
 robot.show_graph(file_name="quadruped.png")
@@ -99,10 +99,10 @@ This saves the robot object to disk as a URDF file named `quadruped.robot`.
 
 ## Result
 
-After running the script, you’ll find the following files in your working directory:
+After running the script, you'll find the following files in your working directory:
 
 1. **Assembly JSON File** (`quadruped.json`): Contains the complete assembly details.
 2. **Assembly Graph** (`quadruped.png`): A visual representation of the assembly’s structure.
 3. **Robot URDF File** (`quadruped.urdf`): A URDF file for simulation.
 
-These files can be used for further analysis, simulation, or into other workflows.
+These files can be used for further analysis, simulation, or integration into other workflows.
diff --git a/examples/export/main.py b/examples/export/main.py
@@ -4,7 +4,7 @@
 from onshape_robotics_toolkit.utilities.helpers import save_model_as_json
 
 if __name__ == "__main__":
-    LOGGER.set_file_name("ballbot.log")
+    LOGGER.set_file_name("quadruped.log")
     LOGGER.set_stream_level(LogLevel.INFO)
     client = Client(env=".env")
 
@@ -18,5 +18,5 @@
 
     save_model_as_json(robot.assembly, "quadruped.json")
 
-    # robot.show_graph(file_name="quadruped.png")
+    robot.show_graph(file_name="quadruped.png")
     robot.save()
