Mirrors/EOS
1
0
Fork 0
mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2025-11-04 00:36:21 +00:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

Update README/CONTRIBUTING Closes #180 (#204)

Browse Source 
* Update README/CONTRIBUTING Closes #180

 * Remove duplicated files in docs/develop and copy them from project
   root to there on documentation generation.

* Makefile: Use fastapi to start server, set port to 8503
This commit is contained in:
Dominique Lasserre
2024-11-17 15:27:43 +01:00
committed by GitHub
parent b3914ab16b
commit edfe309a26
6 changed files with 72 additions and 212 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -1,6 +1,8 @@
cache/ cache/
output/ output/
EOS.config.json EOS.config.json
docs/develop/CONTRIBUTING.md
docs/develop/getting_started.md
# Default ignore folders and files for VS Code, Python # Default ignore folders and files for VS Code, Python

32
CONTRIBUTING.md
View File

@@ -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). 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. 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 ### Code Style
Our code style checks use [`pre-commit`](https://pre-commit.com). 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: To run formatting automatically before every commit:
```bash ```bash

14
Makefile
View File

@@ -16,7 +16,7 @@ help:
@echo " docker-build - Rebuild docker image" @echo " docker-build - Rebuild docker image"
@echo " docs - Generate HTML documentation (in build/docs/html/)." @echo " docs - Generate HTML documentation (in build/docs/html/)."
@echo " read-docs - Read HTML documentation in your browser." @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 " run-dev - Run FastAPI development server in the virtual environment (automatically reloads)."
@echo " dist - Create distribution (in dist/)." @echo " dist - Create distribution (in dist/)."
@echo " clean - Remove generated documentation, distribution and virtual environment." @echo " clean - Remove generated documentation, distribution and virtual environment."
@@ -51,6 +51,12 @@ dist: pip
# Target to generate HTML documentation # Target to generate HTML documentation
docs: pip-dev 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 .venv/bin/sphinx-build -M html docs build/docs
@echo "Documentation generated to build/docs/html/." @echo "Documentation generated to build/docs/html/."
@@ -69,11 +75,11 @@ clean:
run: run:
@echo "Starting FastAPI server, please wait..." @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: run-dev:
@echo "Starting FastAPI development server, please wait..." @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. # Target to setup tests.
test-setup: pip-dev test-setup: pip-dev
@@ -91,7 +97,7 @@ test-full:
# Target to format code. # Target to format code.
format: format:
pre-commit run --all-files .venv/bin/pre-commit run --all-files
# Run entire setup on docker # Run entire setup on docker
docker-run: docker-run:

98
README.md
View File

@@ -8,14 +8,34 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
## Installation ## Installation
Good installation guide: The project requires Python 3.9 or newer. Currently there are no official packages or images published.
<https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/>
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 ## 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 ### 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`. 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 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 ### 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. 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.
### 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
```
## Classes and Functionalities ## Classes and Functionalities
@@ -115,4 +76,9 @@ Each class is designed to be easily customized and extended to integrate additio
## Server API ## 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/)

48
docs/develop/CONTRIBUTING.md
View File

@@ -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/
```

90
docs/develop/getting_started.md
View File

@@ -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
```