Mirrors/EOS
1
0
Fork 0
mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2025-08-25 06:52:23 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Add API documentation generation and use Markdown (#160)

Browse Source 
* Add package API documentation generation

Add generation of the API documentation for akkudoktoreos
and akkudoktoreosserver packages.

The API documentation is generated by the Sphinx autosummary extension.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

* Enable Google style source commenting and documentation generation.

Enable automatic documentation generation from Google style docstrings in the source.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

* Check Google style source commenting.

Check Google style commenting by the appropriate ruff rules.

Commenting is _NOT_ enforced. Missing docstrings are ignored.

Minor commenting quirks of the code base are adapted.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

* Improve Markdown handling and switch to Markdown documentation.

Switch to Markdown for the documentation files to improve the user and developer experience (see issue #181).

Keep files with special directives for automatic API documentation in RST format. The
directives expect RST.

Also add dummy handling for openai/ swagger server documentation. The openai interface definition is
for now taken from the fastapi PR as EOS will switch to fastAPI.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

---------

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
Co-authored-by: Normann <github@koldrack.com>
This commit is contained in:
Bobby Noelte
2024-11-10 23:27:52 +01:00
committed by GitHub
parent ef93574f87
commit 6561793e3b
28 changed files with 1287 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/develop/getting_started.rst → docs/develop/getting_started.md
View File

@@ -1,20 +1,15 @@
..
SPDX-License-Identifier: Apache-2.0
% SPDX-License-Identifier: Apache-2.0
.. _akkudoktoreos_getting_started:
# Getting Started
Getting Started
###############
## Installation
Installation
************
`Good installation guide <https://meintechblog.de/2024/09/05/andreas-schmitz-joerg-installiert-mein-energieoptimierungssystem/>`_
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
-----------------
### Quick Start Guide
On Linux (Ubuntu/Debian):
@@ -22,7 +17,7 @@ On Linux (Ubuntu/Debian):
sudo apt install make
```
On MacOS (requires `Homebrew <https://brew.sh>`_):
On MacOS (requires [Homebrew](https://brew.sh)):
```zsh
brew install make
@@ -31,8 +26,7 @@ brew install make
Next, adjust `config.py`.
The server can then be started with `make run`. A full overview of the main shortcuts is given by `make help`.
Detailed Instructions
---------------------
### Detailed Instructions
All necessary dependencies can be installed via `pip`. Clone the repository and install the required packages with:
@@ -63,22 +57,12 @@ source .venv/bin/activate
```zsh
. .venv/bin/activate
```
(if using zsh, primarily for MacOS users).
If `pip install` fails to install the mariadb dependency, the following commands may help:
* Debian/Ubuntu: `sudo apt-get install -y libmariadb-dev`
* MacOS/Homebrew: `brew install mariadb-connector-c`
Followed by a renewed `pip install -r requirements.txt`.
Usage
*****
## Usage
Adjust `config.py`.
To start the server:
To use the system, run `flask_server.py`, which starts the server:
```bash
make run
./flask_server.py
```