Merge branch 'dev'

kks32 · kks32 · commit e250f567a862 · 2025-06-06T07:40:59.000-05:00
diff --git a/docs/api/apps.md b/docs/api/apps.md
@@ -0,0 +1,11 @@
+# Apps
+
+Application discovery and management for DesignSafe computational applications.
+
+## Application Discovery
+
+::: dapi.apps.find_apps
+
+## Application Details
+
+::: dapi.apps.get_app_details
diff --git a/docs/api/auth.md b/docs/api/auth.md
@@ -0,0 +1,7 @@
+# Auth
+
+Authentication and credential management for DesignSafe access.
+
+## Authentication
+
+::: dapi.auth.init
diff --git a/docs/api/client.md b/docs/api/client.md
@@ -0,0 +1,25 @@
+# DSClient
+
+The main client interface for all DAPI functionality. DSClient provides organized access to DesignSafe resources through the Tapis V3 API.
+
+::: dapi.client.DSClient
+
+## Service Interfaces
+
+The DSClient provides access to different DesignSafe services through specialized interface classes:
+
+### AppMethods
+
+::: dapi.client.AppMethods
+
+### FileMethods
+
+::: dapi.client.FileMethods
+
+### JobMethods
+
+::: dapi.client.JobMethods
+
+### SystemMethods
+
+::: dapi.client.SystemMethods
diff --git a/docs/api/database.md b/docs/api/database.md
@@ -0,0 +1,15 @@
+# Database
+
+Database connections and query execution for DesignSafe research databases.
+
+## Database Accessor
+
+::: dapi.db.accessor.DatabaseAccessor
+
+## Database Engine
+
+::: dapi.db.db.DSDatabase
+
+## Database Configuration
+
+::: dapi.db.config.db_config
diff --git a/docs/api/exceptions.md b/docs/api/exceptions.md
@@ -0,0 +1,29 @@
+# Exceptions
+
+Custom exception classes for DAPI error handling and debugging.
+
+## Base Exception
+
+::: dapi.exceptions.DapiException
+
+## Authentication Exceptions
+
+::: dapi.exceptions.AuthenticationError
+
+## File Operation Exceptions
+
+::: dapi.exceptions.FileOperationError
+
+## Application Discovery Exceptions
+
+::: dapi.exceptions.AppDiscoveryError
+
+## System Information Exceptions
+
+::: dapi.exceptions.SystemInfoError
+
+## Job Management Exceptions
+
+::: dapi.exceptions.JobSubmissionError
+
+::: dapi.exceptions.JobMonitorError
diff --git a/docs/api/files.md b/docs/api/files.md
@@ -0,0 +1,21 @@
+# Files
+
+File operations and path translation utilities for DesignSafe storage systems.
+
+## Path Translation
+
+::: dapi.files.get_ds_path_uri
+
+::: dapi.files.tapis_uri_to_local_path
+
+## File Operations
+
+::: dapi.files.upload_file
+
+::: dapi.files.download_file
+
+::: dapi.files.list_files
+
+## Utility Functions
+
+::: dapi.files._parse_tapis_uri
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -0,0 +1,83 @@
+# API Reference
+
+This section provides comprehensive API documentation for all DAPI modules and classes, automatically generated from docstrings.
+
+## 📋 Overview
+
+The DAPI package is organized into several core modules:
+
+### **Core Client**
+- **[DSClient](client.md)** - Main client interface for all DAPI functionality
+
+### **Service Modules**
+- **[Jobs](jobs.md)** - Job submission, monitoring, and management
+- **[Files](files.md)** - File operations and path translation
+- **[Apps](apps.md)** - Application discovery and details
+- **[Systems](systems.md)** - System information and queue management
+- **[Auth](auth.md)** - Authentication and credential management
+
+### **Database Access**
+- **[Database](database.md)** - Database connections and query execution
+
+### **Utilities**
+- **[Exceptions](exceptions.md)** - Custom exception classes
+
+## 🚀 Quick Navigation
+
+### **Getting Started**
+```python
+from dapi import DSClient
+
+# Initialize client
+client = DSClient()
+
+# Access different services
+client.jobs.generate_request(...)
+client.files.upload(...)
+client.db.ngl.read_sql(...)
+```
+
+### **Common Operations**
+- **Submit Jobs**: `client.jobs.submit_request(job_dict)`
+- **Monitor Jobs**: `submitted_job.monitor()`
+- **File Upload**: `client.files.upload(local_path, remote_uri)`
+- **File Download**: `client.files.download(remote_uri, local_path)`
+- **Database Query**: `client.db.ngl.read_sql("SELECT * FROM table")`
+
+### **Advanced Features**
+- **Archive Management**: Custom job result organization
+- **Path Translation**: Seamless local/cloud path conversion
+- **Parametric Studies**: Batch job submission and monitoring
+- **Error Handling**: Comprehensive exception hierarchy
+
+## 📖 Documentation Conventions
+
+### **Parameter Types**
+- `Optional[Type]` - Parameter can be `None`
+- `Union[Type1, Type2]` - Parameter accepts multiple types
+- `List[Type]` - List containing elements of specified type
+- `Dict[str, Any]` - Dictionary with string keys and any values
+
+### **Return Types**
+- Methods clearly document return types and formats
+- Async methods return appropriate async types
+- Error conditions are documented in `Raises` sections
+
+### **Examples**
+Each method includes practical usage examples showing:
+- Basic usage patterns
+- Parameter combinations
+- Error handling
+- Integration with other DAPI components
+
+## 🔗 Cross-References
+
+The API documentation includes extensive cross-references:
+- **Method signatures** link to parameter and return types
+- **Related methods** are referenced in descriptions
+- **Example workflows** demonstrate method integration
+- **Error handling** shows exception hierarchies
+
+---
+
+**Browse the API documentation using the navigation menu to explore specific modules and their functionality.**
diff --git a/docs/api/jobs.md b/docs/api/jobs.md
@@ -0,0 +1,35 @@
+# Jobs
+
+Job submission, monitoring, and management functionality for DesignSafe computational workflows.
+
+## Job Request Generation
+
+::: dapi.jobs.generate_job_request
+
+## Job Submission
+
+::: dapi.jobs.submit_job_request
+
+## Job Monitoring
+
+::: dapi.jobs.get_job_status
+
+::: dapi.jobs.get_runtime_summary
+
+::: dapi.jobs.interpret_job_status
+
+## SubmittedJob Class
+
+::: dapi.jobs.SubmittedJob
+
+## Status Constants
+
+::: dapi.jobs.STATUS_TIMEOUT
+
+::: dapi.jobs.STATUS_INTERRUPTED
+
+::: dapi.jobs.STATUS_MONITOR_ERROR
+
+::: dapi.jobs.STATUS_UNKNOWN
+
+::: dapi.jobs.TAPIS_TERMINAL_STATES
diff --git a/docs/api/systems.md b/docs/api/systems.md
@@ -0,0 +1,7 @@
+# Systems
+
+System information and queue management for DesignSafe execution systems.
+
+## System Queues
+
+::: dapi.systems.list_system_queues
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -37,6 +37,21 @@ theme:
 
 plugins:
   - search
+  - autorefs
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            show_source: true
+            show_if_no_docstring: true
+            inherited_members: true
+            members_order: source
+            separate_signature: true
+            unwrap_annotated: true
+            filters: ["!^_"]
+            merge_init_into_class: true
+            docstring_section_style: spacy
 
 markdown_extensions:
   - pymdownx.highlight:
@@ -67,6 +82,16 @@ nav:
     - MPM Job Submission: examples/mpm.md
     - OpenSees Job Submission: examples/opensees.md
     - Database Queries: examples/database.md
+  - API Reference:
+    - Overview: api/index.md
+    - DSClient: api/client.md
+    - Jobs: api/jobs.md
+    - Files: api/files.md
+    - Apps: api/apps.md
+    - Systems: api/systems.md
+    - Database: api/database.md
+    - Auth: api/auth.md
+    - Exceptions: api/exceptions.md
 
 extra:
   social:
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
