mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2025-04-19 08:55:15 +00:00

Add API documentation generation and use Markdown (#160 )

* 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>

2024-11-10 23:27:52 +01:00

1.3 KiB

Raw Blame History

% 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):

sudo apt install make

On MacOS (requires Homebrew):

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

All necessary dependencies can be installed via pip. Clone the repository and install the required packages with:

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:

virtualenv .venv

Finally, install the Python dependencies for EOS:

.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:

source .venv/bin/activate

(for Bash users, the default under Linux) or

. .venv/bin/activate

Usage

Adjust config.py. To use the system, run flask_server.py, which starts the server:

./flask_server.py

1.3 KiB Raw Blame History