mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2025-04-19 08:55:15 +00:00
* 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
GitHub
parent
e936aaf134
commit
e18201dcb3
2
.gitignore
vendored
2
.gitignore
vendored
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
14
Makefile
14
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:
|
||||
|
||||
98
README.md
98
README.md
@ -8,14 +8,34 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## Installation
|
||||
|
||||
Good installation guide:
|
||||
<https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/>
|
||||
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/)
|
||||
|
||||
@ -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/
|
||||
```
|
||||
@ -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
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user