diff --git a/.gitignore b/.gitignore index e8848e2..338a6ae 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ cache/ output/ EOS.config.json +docs/develop/CONTRIBUTING.md +docs/develop/getting_started.md # Default ignore folders and files for VS Code, Python diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6b6444..d78e730 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,14 +19,38 @@ There are just too many possibilities and the project would drown in tickets oth We welcome code contributions and bug fixes via [Pull Requests](https://github.com/Akkudoktor-EOS/EOS/pulls). To make collaboration easier, we require pull requests to pass code style and unit tests. + +### Setup development environment + +Setup virtual environment, then activate virtual environment and install development dependencies. +See also [README.md](README.md). + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r requirements-dev.txt +``` + +Install make to get access to helpful shortcuts (documentation generation, manual formatting, etc.). + +- On Linux (Ubuntu/Debian): + + ```bash + sudo apt install make + ``` + +- On MacOS (requires [Homebrew](https://brew.sh)): + + ```zsh + brew install make + ``` + +The server can be started with `make run`. A full overview of the main shortcuts is given by `make help`. + ### Code Style Our code style checks use [`pre-commit`](https://pre-commit.com). -```bash -pip install -r requirements-dev.txt -``` - To run formatting automatically before every commit: ```bash diff --git a/Makefile b/Makefile index eab10be..4d23186 100644 --- a/Makefile +++ b/Makefile @@ -16,7 +16,7 @@ help: @echo " docker-build - Rebuild docker image" @echo " docs - Generate HTML documentation (in build/docs/html/)." @echo " read-docs - Read HTML documentation in your browser." - @echo " run - Run FastAPI server in the virtual environment (needs install before)." + @echo " run - Run FastAPI production server in the virtual environment." @echo " run-dev - Run FastAPI development server in the virtual environment (automatically reloads)." @echo " dist - Create distribution (in dist/)." @echo " clean - Remove generated documentation, distribution and virtual environment." @@ -51,6 +51,12 @@ dist: pip # Target to generate HTML documentation docs: pip-dev + cp README.md docs/develop/getting_started.md + # remove top level header and coresponding description + sed -i '/^##[^#]/,$$!d' docs/develop/getting_started.md + sed -i "1i\# Getting Started\n" docs/develop/getting_started.md + cp CONTRIBUTING.md docs/develop + sed -i "s/README.md/getting_started.md/g" docs/develop/CONTRIBUTING.md .venv/bin/sphinx-build -M html docs build/docs @echo "Documentation generated to build/docs/html/." @@ -69,11 +75,11 @@ clean: run: @echo "Starting FastAPI server, please wait..." - .venv/bin/python -m akkudoktoreos.server.fastapi_server + .venv/bin/fastapi run --port 8503 src/akkudoktoreos/server/fastapi_server.py run-dev: @echo "Starting FastAPI development server, please wait..." - .venv/bin/fastapi dev src/akkudoktoreos/server/fastapi_server.py + .venv/bin/fastapi dev --port 8503 src/akkudoktoreos/server/fastapi_server.py # Target to setup tests. test-setup: pip-dev @@ -91,7 +97,7 @@ test-full: # Target to format code. format: - pre-commit run --all-files + .venv/bin/pre-commit run --all-files # Run entire setup on docker docker-run: diff --git a/README.md b/README.md index f3743f1..7fe9a53 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,34 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). ## Installation -Good installation guide: - +The project requires Python 3.9 or newer. Currently there are no official packages or images published. -The project requires Python 3.10 or newer. +Following sections describe how to locally start the EOS server on `http://localhost:8503`. + +### Run from source + +Install dependencies in virtual environment: + +```bash +python -m venv .venv +.venv/bin/pip install -r requirements.txt +``` + +Finally, start EOS fastapi server: + +```bash +.venv/bin/fastapi run --port 8503 src/akkudoktoreos/server/fastapi_server.py +``` + +### Docker + +```bash +docker compose up --build +``` ## Configuration -This project uses a `config.json` file to manage configuration settings. +This project uses the `EOS.config.json` file to manage configuration settings. ### Default Configuration @@ -26,70 +46,11 @@ A default configuration file `default.config.json` is provided. This file contai Users can specify a custom configuration directory by setting the environment variable `EOS_DIR`. - If the directory specified by `EOS_DIR` contains an existing `config.json` file, the application will use this configuration file. -- If the `config.json` file does not exist in the specified directory, the `default.config.json` file will be copied to the directory as `config.json`. +- If the `EOS.config.json` file does not exist in the specified directory, the `default.config.json` file will be copied to the directory as `EOS.config.json`. ### Configuration Updates -If the configuration keys in the `config.json` file are missing or different from those in `default.config.json`, they will be automatically updated to match the default settings, ensuring that all required keys are present. - -### Quick Start Guide - -On Linux (Ubuntu/Debian): - -```bash -sudo apt install make -``` - -On MacOS (requires [Homebrew](https://brew.sh)): - -```zsh -brew install make -``` - -The server can be started with `make run`. A full overview of the main shortcuts is given by `make help`. - -### Detailed Instructions - -All necessary dependencies can be installed via `pip`. Clone the repository and install the required packages with: - -```bash -git clone https://github.com/Akkudoktor-EOS/EOS -cd EOS -``` - -Next, create a virtual environment. This serves to store the Python dependencies, which we will install later using `pip`: - -```bash -python -m venv .venv -``` - -Finally, install the Python dependencies for EOS: - -```bash -.venv/bin/pip install -r requirements.txt -``` - -To always use the Python version from the virtual environment, you should activate it before working in EOS: - -```bash -source .venv/bin/activate -``` - -## Usage - -To use the system and start the server, run `fastapi_server.py` in the previously activated virtual environment: - -```bash -fastapi run src/akkudoktoreos/server/fastapi_server.py -``` - -### Docker - -To run the system with Docker: - -```bash -docker compose up --build -``` +If the configuration keys in the `EOS.config.json` file are missing or different from those in `default.config.json`, they will be automatically updated to match the default settings, ensuring that all required keys are present. ## Classes and Functionalities @@ -115,4 +76,9 @@ Each class is designed to be easily customized and extended to integrate additio ## Server API -See the Swagger documentation for detailed information: [EOS OpenAPI Spec](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/docs/akkudoktoreos/openapi.json) +See the Swagger API documentation for detailed information: [EOS OpenAPI Spec](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/docs/akkudoktoreos/openapi.json) + + +## Further resources + + - [Installation guide (de)](https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/) diff --git a/docs/develop/CONTRIBUTING.md b/docs/develop/CONTRIBUTING.md deleted file mode 100644 index e4fbc3d..0000000 --- a/docs/develop/CONTRIBUTING.md +++ /dev/null @@ -1,48 +0,0 @@ -# Contributing to EOS - -Thanks for taking the time to read this! - -The `EOS` project is in early development, therefore we encourage contribution in the following ways: - -## Bug Reports - -Please report flaws or vulnerabilities in the [GitHub Issue Tracker]((https://github.com/Akkudoktor-EOS/EOS/issues)) using the corresponding issue template. - -## Ideas & Features - -Please first discuss the idea in a [GitHub Discussion](https://github.com/Akkudoktor-EOS/EOS/discussions) or the [Akkudoktor Forum](https://www.akkudoktor.net/forum/diy-energie-optimierungssystem-opensource-projekt/) before opening an issue. - -There are just too many possibilities and the project would drown in tickets otherwise. - -## Code Contributions - -We welcome code contributions and bug fixes via [Pull Requests](https://github.com/Akkudoktor-EOS/EOS/pulls). -To make collaboration easier, we require pull requests to pass code style and unit tests. - -### Code Style - -Our code style checks use [`pre-commit`](https://pre-commit.com). - -```bash -pip install -r requirements.txt -``` - -To run formatting automatically before every commit: - -```bash -pre-commit install -``` - -Or run them manually: - -```bash -pre-commit --all -``` - -### Tests - -Use `pytest` to run tests locally: - -```bash -python -m pytest -vs --cov modules --cov-report term-missing tests/ -``` diff --git a/docs/develop/getting_started.md b/docs/develop/getting_started.md deleted file mode 100644 index d6dc72c..0000000 --- a/docs/develop/getting_started.md +++ /dev/null @@ -1,90 +0,0 @@ -% SPDX-License-Identifier: Apache-2.0 - -# Getting Started - -## Installation - -Good installation guide: -https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/ - -The project requires Python 3.10 or newer. - -### Quick Start Guide - -On Linux (Ubuntu/Debian): - -```bash -sudo apt install make -``` - -On MacOS (requires [Homebrew](https://brew.sh)): - -```zsh -brew install make -``` - -The server can then be started with `make run`. A full overview of the main shortcuts is given by `make help`. - -### Detailed Instructions - -All necessary dependencies can be installed via `pip`. Clone the repository and install the required packages with: - -```bash -git clone https://github.com/Akkudoktor-EOS/EOS -cd EOS -``` - -Next, create a virtual environment. This serves to store the Python dependencies, which we will install later using `pip`: - -```bash -virtualenv .venv -``` - -Finally, install the Python dependencies for EOS: - -```bash -.venv/bin/pip install -r requirements.txt -``` - -To always use the Python version from the virtual environment, you should activate it before working in EOS: - -```bash -source .venv/bin/activate -``` - -(for Bash users, the default under Linux) or - -```zsh -. .venv/bin/activate -``` - -## Usage - -### Configuration - ---- - -This project uses a `config.json` file to manage configuration settings. - -#### Default Configuration - -A default configuration file `default.config.json` is provided. This file contains all the necessary configuration keys with their default values. - -#### Custom Configuration - -Users can specify a custom configuration directory by setting the environment variable `EOS_DIR`. - -- If the directory specified by `EOS_DIR` contains an existing `config.json` file, the application will use this configuration file. -- If the `config.json` file does not exist in the specified directory, the `default.config.json` file will be copied to the directory as `config.json`. - -#### Configuration Updates - -If the configuration keys in the `config.json` file are missing or different from those in `default.config.json`, they will be automatically updated to match the default settings, ensuring that all required keys are present. - -### Run server - -To use the system, run `flask_server.py`, which starts the server: - -```bash -./flask_server.py -```