diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..5e202b0 --- /dev/null +++ b/.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 diff --git a/docs/CodeBase/powerstation_simulator.md b/docs/CodeBase/powerstation_simulator.md new file mode 100644 index 0000000..c9b80af --- /dev/null +++ b/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 diff --git a/docs/README.md b/docs/README.md index 43383ff..0e48d67 100644 --- a/docs/README.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index e24757d..1b82936 100644 --- a/mkdocs.yml +++ b/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 diff --git a/src/powerstation_simulator/logger.py b/src/powerstation_simulator/logger.py index 523f5be..d8496bc 100644 --- a/src/powerstation_simulator/logger.py +++ b/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. diff --git a/src/powerstation_simulator/station_simulator.py b/src/powerstation_simulator/station_simulator.py index 17e203e..3e34869 100644 --- a/src/powerstation_simulator/station_simulator.py +++ b/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.