Update README/CONTRIBUTING Closes #180 (#204)

* 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

.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
 

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

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:

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.
-<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
 
-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.
+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
 
@@ -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/)

docs/develop/CONTRIBUTING.md

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

docs/develop/getting_started.md

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