Merge pull request #5 from extinctCoder/sas-branch-7

feat: add typing, docs deploy workflow, and logger typing

Author: extinctCoder

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Documentation Deployment
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  DeployMkdocs:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code repository
+        id: code_checkout
+        uses: actions/checkout@v4
+
+      - name: Setup python environment
+        id: setup_python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install the required python modules
+        id: module_installation
+        run: |
+          python -m pip install -r requirements.docs.txt
+
+      - name: Deploy Documentation on gh-pages branch
+        id: deploy_mkdocs
+        run: |
+          mkdocs gh-deploy --force

docs/CodeBase/powerstation_simulator.md

@@ -0,0 +1,15 @@
+# Power Station Simulator
+
+This section contains the Python API documentation for the power station simulation code.
+
+The following modules are documented here:
+
+::: powerstation_simulator.main
+
+::: powerstation_simulator.station_simulator
+
+::: powerstation_simulator.mqtt_client
+
+::: powerstation_simulator.config
+
+::: powerstation_simulator.logger

docs/README.md

@@ -1,24 +1,14 @@
-# Welcome to MkDocs
+# Smart Grid Simulator
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+The Smart Grid Simulator is a virtual power station network designed to emulate real-world power generation and distribution. It allows testing and monitoring of smart grid systems without relying on physical hardware.
 
-## Commands
+## Key Features
+- Simulated Power Stations: Generate realistic power output based on configurable parameters.
+- Real-Time Data Publishing: Station metadata, output, and status are continuously published via MQTT.
+- Configurable & Extensible: Easily set up multiple stations using environment variables or configuration files.
+- Monitoring Ready: Data can be visualized through dashboards or consumed by other applications.
 
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
-
-## Project layout
-
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
-
-
-
-1. [[mash network|mash_network]]
-2. [[current sensor|current sensor]]
-3. [[voltage sensor|voltage sensor]]
-4.
+## Use Cases
+- Test smart grid applications safely and efficiently.
+- Prototype dashboards and analytics for power monitoring.
+- Simulate renewable and conventional energy sources.

mkdocs.yml

@@ -1,7 +1,17 @@
 site_name: Smart Grid
+repo_url: https://github.com/extinctCoder/smart_grid
+edit_uri: https://github.com/extinctCoder/smart_grid/docs
+
+site_author: extinctCoder
+site_description: "A smart grid project for efficient energy management."
+site_url: https://extinctcoder.github.io/smart_grid
+copyright: MIT License
 
 theme:
   name: material
+  font:
+    text: "Roboto"
+    code: "Fira Code"
 
 docs_dir: docs
 site_dir: site

src/powerstation_simulator/logger.py

@@ -1,5 +1,6 @@
 import logging
 import sys
+from logging import Logger, LogRecord
 
 COLORS = {
     "DEBUG": "\033[34m",  # BLUE
@@ -22,7 +23,7 @@ class ColoredFormatter(logging.Formatter):
         format: Overrides the base Formatter's format method to add colors.
     """
 
-    def format(self, record) -> str:
+    def format(self, record: LogRecord) -> str:
         """
         Format the specified record with colored level names.
 
@@ -38,7 +39,7 @@ def format(self, record) -> str:
         return super().format(record)
 
 
-def setup_base_logger(level=logging.DEBUG):
+def setup_base_logger(level: int | str = logging.DEBUG) -> Logger:
     """
     Configure and return the root logger with colored output.
 
@@ -47,11 +48,12 @@ def setup_base_logger(level=logging.DEBUG):
     logger already has handlers configured, this function does nothing.
 
     Args:
-        level: The logging level to set for the root logger.
-               Default is logging.DEBUG.
+        level:
+            The logging level to set for the root logger.
+            Default is logging.DEBUG.
 
     Returns:
-        logging.Logger: The configured root logger instance.
+        Logger: The configured root logger instance.
     """
     root_logger = logging.getLogger()
     if not root_logger.hasHandlers():
@@ -65,7 +67,7 @@ def setup_base_logger(level=logging.DEBUG):
     return root_logger
 
 
-def getLogger(name: str):
+def getLogger(name: str) -> Logger:
     """
     Get a logger with the specified name, ensuring the base logger is configured.
 

src/powerstation_simulator/station_simulator.py

@@ -1,6 +1,7 @@
 from random import random
 from threading import Thread
 from time import sleep
+from typing import Any
 
 from config import AppConfig
 from logger import getLogger
@@ -173,7 +174,7 @@ def __publish_output_loop(self):
             self.publish_output()
             sleep(self.app_config.PUBLISH_INTERVAL_SECONDS)
 
-    def __handle_control(self, client, userdata, message):
+    def __handle_control(self, client: Any, userdata: Any, message: Any):
         """
         Callback handler for MQTT control messages.