Merge pull request #3 from pnnl-int/documentation

Documentation

Author: yanyanzhu-pnnl

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build documentation
+        run: uv run mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -53,3 +53,6 @@ htmlcov/
 
 .env
 testprojectJson/
+
+# MkDocs build output
+site/

comcheck_api/api/api_services.py

@@ -23,7 +23,17 @@
 
 
 class COMCheckApiService:
-    """COMCheck API service class for interacting with the COM API."""
+    """Low-level HTTP service for the COMcheck Web API.
+
+    Handles authentication, request construction, response parsing, and
+    error mapping.  Methods accept raw dicts as inputs and return either
+    raw dicts or validated Pydantic response models.
+
+    Can be used as a context manager::
+
+        with COMCheckApiService(api_key="key") as svc:
+            data = svc.get_project("123")
+    """
 
     def __init__(self, api_key: str) -> None:
         """Initialize COMCheck API service.

comcheck_api/client/comcheck_client.py

@@ -18,7 +18,26 @@
 
 
 class COMcheckClient:
-    """COMcheck Client class for simplified project operations."""
+    """High-level client for the COMcheck Web API.
+
+    Provides user-friendly methods that accept Pydantic models as inputs
+    and return either :class:`~comcheck_api.types.core_types.ComBuilding`
+    models, primitives, or raw dicts depending on the operation.
+
+    Can be used as a context manager to ensure the underlying HTTP
+    connection is closed::
+
+        with COMcheckClient(api_key="your-key") as client:
+            project = client.get_project("123")
+
+    Example:
+        ```python
+        client = COMcheckClient(api_key="your-key")
+        projects = client.list_projects()
+        project = client.get_project(projects[0]["projectId"])
+        client.close()
+        ```
+    """
 
     def __init__(self, api_key: Optional[str] = None) -> None:
         """Initialize COMcheck client.
@@ -116,15 +135,21 @@ def update_project(
     ) -> ComBuilding | dict[str, Any] | None:
         """Update a project by ID.
 
+        The existing project is fetched first to preserve server-assigned IDs
+        and the ``userProject`` reference.  Envelope component IDs that are
+        ``None`` (auto-generated by Pydantic) are stripped before submission.
+
         Args:
-            project_id: The project ID to update
-            project_data: The project data to send in the request body
+            project_id: The project ID to update.
+            project_data: A ``ComBuilding`` model with the desired state.
+            mode: ``"python"`` returns a ``ComBuilding`` model;
+                ``"json"`` returns a raw dict.
 
         Returns:
-            API response data as dictionary
+            The refreshed project after the update, in the requested format.
 
         Raises:
-            COMCheckProjectNotFoundError: If project is not found
+            COMCheckProjectNotFoundError: If the project does not exist.
         """
         # Get existing project
         old_project = self.get_project(project_id, mode="json")
@@ -222,13 +247,22 @@ def _parse_data(self, data, mode):
     def start_run_simulation(
         self, project: ComBuilding, project_id: Optional[int] = None
     ) -> str:
-        """Start a simulation run for a given project.
+        """Start a compliance simulation run for a project.
+
+        If *project_id* is supplied the project is persisted via
+        :meth:`update_project` before the simulation is launched.
 
         Args:
-            project: The project data to run the simulation
-            project_id: Optional project ID, if not provided, project won't be saved
+            project: The project data to simulate.
+            project_id: Optional server-side project ID.  When given, the
+                project is saved before the simulation starts.
+
         Returns:
-            Simulation session ID
+            The simulation session ID that can be passed to
+            :meth:`get_simulation_status` and :meth:`get_simulation_result`.
+
+        Raises:
+            COMCheckSimulationError: If the API returns no session data.
         """
         logger = logging.getLogger(__name__)
 
@@ -245,13 +279,16 @@ def start_run_simulation(
         return run_result.data.sessionId
 
     def get_simulation_status(self, session_id: str) -> Dict[str, Any]:
-        """Get the status of a simulation run by session ID.
+        """Get the status of a running or completed simulation.
 
         Args:
-            session_id: The simulation session ID
+            session_id: The session ID returned by :meth:`start_run_simulation`.
 
         Returns:
-            Simulation status information
+            A dict containing ``sessionId``, ``status``, and optional ``message``.
+
+        Raises:
+            COMCheckSimulationError: If the status cannot be retrieved.
         """
         status_response = self._service.get_simulation_status(session_id)
         if status_response.data is None:
@@ -261,13 +298,18 @@ def get_simulation_status(self, session_id: str) -> Dict[str, Any]:
         return status_response.data.model_dump(mode="python")
 
     def get_simulation_result(self, session_id: str) -> Dict[str, Any]:
-        """Get the result of a simulation run by session ID.
+        """Get the result metrics of a completed simulation.
 
         Args:
-            session_id: The simulation session ID
+            session_id: The session ID returned by :meth:`start_run_simulation`.
 
         Returns:
-            Simulation result information
+            A dict containing ``sessionId``, ``performanceRating``,
+            ``energyCreditPerformanceRating``, ``proposedBpf``, and
+            ``baselineBpf``.
+
+        Raises:
+            COMCheckSimulationError: If the result cannot be retrieved.
         """
         result_response = self._service.get_simulation_result(session_id)
         if result_response.data is None:

comcheck_api/constants/common_constants.py

@@ -1,3 +1,10 @@
+"""Default project template used to bootstrap new COMcheck projects.
+
+The :data:`PROJECT_TEMPLATE` constant is a fully validated :class:`ComBuilding`
+instance pre-populated with sensible defaults for all required sections
+(envelope, lighting, HVAC, location, etc.).
+"""
+
 from comcheck_api.types.core_types import ComBuilding
 
 PROJECT_TEMPLATE = ComBuilding.model_validate(

comcheck_api/exceptions.py

@@ -24,19 +24,19 @@ def __init__(self, status_code: int, message: str, response_data: str = ""):
 
 
 class COMCheckValidationError(COMCheckAPIError):
-    """Validation failed."""
+    """Raised when request or response data fails Pydantic or schema validation."""
 
     pass
 
 
 class COMCheckConnectionError(COMCheckAPIError):
-    """Connection to COMcheck API failed."""
+    """Raised when the HTTP client cannot reach the COMcheck API server."""
 
     pass
 
 
 class COMCheckSimulationError(COMCheckAPIError):
-    """Simulation-related error."""
+    """Raised when a simulation request fails or returns unexpected data."""
 
     pass
 

comcheck_api/managers/data_manager.py

@@ -43,7 +43,14 @@ def __init__(
         model_type: Type[BaseModel] | None = None,
         schema_path: str | Path = "../schemas/comCheck.schema.json",
     ):
-        """Initialize the data manager."""
+        """Initialize the data manager.
+
+        Args:
+            initial_data: Items to pre-populate the manager with.
+            model_type: Pydantic model class for the managed items.
+                Falls back to the class-level ``model_type`` attribute.
+            schema_path: Path to a JSON schema file for validation.
+        """
         self._data: list[T] = []
         self._schema: dict[str, Any] | None = None
 
@@ -77,7 +84,11 @@ def _initialize_metadata(self, model_type: BaseModel | None = None) -> None:
             )
 
     def _initialize_schema(self, schema_path: str | Path) -> None:
-        """Load schema if provided"""
+        """Load the JSON schema from disk if the file exists.
+
+        Args:
+            schema_path: Path to the JSON schema file.
+        """
         if schema_path:
             schema_path = Path(schema_path)
             if schema_path.exists():
@@ -147,11 +158,16 @@ def add_new(self, item: T | dict[str, Any]) -> list[T]:
         return self.get_all()
 
     def generate_identifier(self, item: T) -> None:
-        """
-        Ensures the item has a valid and unique identifier.
+        """Ensure the item has a valid and unique identifier.
+
+        If the identifier is missing, invalid, duplicated, or does not match
+        the expected prefix, a new unique one is generated via the ID registry.
 
-        If the identifier is missing, invalid, duplicated, or does not match the
-        expected prefix, generate a new unique one.
+        Args:
+            item: The item whose identifier should be validated or assigned.
+
+        Raises:
+            Exception: If the item is already present in the managed list.
         """
         if any(existing is item for existing in self._data):
             raise Exception("Item already exists in managed list")

comcheck_api/types/__init__.py

@@ -17,7 +17,17 @@
 
 
 def _collect_exports(mod: ModuleType) -> List[str]:
-    """Collect exportable names from a module."""
+    """Collect public names exported by a module.
+
+    Uses the module's ``__all__`` list when available; otherwise falls back to
+    all names that do not start with an underscore.
+
+    Args:
+        mod: The module to inspect.
+
+    Returns:
+        List of exportable name strings.
+    """
     if hasattr(mod, "__all__"):
         return list(mod.__all__)
     return [name for name in dir(mod) if not name.startswith("_")]

comcheck_api/types/api_types.py

@@ -1,34 +1,86 @@
+"""Pydantic models for COMcheck API request and response payloads.
+
+These models represent the JSON structures returned by the COMcheck Web API
+and are used internally by :class:`~comcheck_api.api.COMCheckApiService` and
+:class:`~comcheck_api.client.COMcheckClient` for type-safe deserialization.
+"""
+
 from typing import Any
 from pydantic import BaseModel, ConfigDict
 
 
 class ApiResponse(BaseModel):
+    """Base model for all COMcheck API responses.
+
+    Attributes:
+        success: Whether the API call succeeded.
+        message: Optional human-readable message from the server.
+        data: Response payload (type varies by endpoint).
+        errors: List of error strings, if any.
+    """
+
     success: bool
     message: str | None = None
     data: Any = None
     errors: list[str] | None = None
 
 
 class SessionInfo(BaseModel):
+    """Session metadata returned when a simulation is started.
+
+    Attributes:
+        sessionId: Unique identifier for the simulation session.
+    """
+
     model_config = ConfigDict(extra="allow")
     sessionId: str
 
 
 class RunSimulationResponse(ApiResponse):
+    """Response from the ``start-run-simulation`` endpoint.
+
+    Attributes:
+        data: Session information for the started simulation, or ``None`` on failure.
+    """
+
     data: SessionInfo | None = None
 
 
 class StatusInfo(BaseModel):
+    """Simulation status details.
+
+    Attributes:
+        sessionId: The simulation session identifier.
+        status: Current status string (e.g. ``"COMPLETED"``, ``"IN_PROGRESS"``).
+        message: Optional status message from the server.
+    """
+
     sessionId: str
     status: str
     message: str | None = None
 
 
 class SimulationStatusResponse(ApiResponse):
+    """Response from the ``get-status-simulation`` endpoint.
+
+    Attributes:
+        data: Status details for the queried session, or ``None`` on failure.
+    """
+
     data: StatusInfo | None = None
 
 
 class SimulationResultInfo(BaseModel):
+    """Simulation result metrics.
+
+    Attributes:
+        sessionId: The simulation session identifier.
+        performanceRating: Overall performance rating (percentage).
+        energyCreditPerformanceRating: Energy credit performance rating.
+        proposedBpf: Proposed building performance factor.
+        baselineBpf: Baseline building performance factor.
+    """
+
     sessionId: str
     performanceRating: float | None = None
     energyCreditPerformanceRating: float | None = None
@@ -37,4 +89,10 @@ class SimulationResultInfo(BaseModel):
 
 
 class SimulationResultResponse(ApiResponse):
+    """Response from the ``get-result-simulation`` endpoint.
+
+    Attributes:
+        data: Result metrics for the queried session, or ``None`` on failure.
+    """
+
     data: SimulationResultInfo | None = None