From ae86a612f95f307c9797ebf23b8b0a80265b6df3 Mon Sep 17 00:00:00 2001
From: David Trattnig <david.trattnig@o94.at>
Date: Thu, 30 Apr 2020 10:21:53 +0200
Subject: [PATCH] Extended structure with links.
---
README.md | 10 +++++++-
docs/configuration-guide.md | 14 +++++++++-
docs/developer-guide.md | 44 ++++++++++++++++++++------------
docs/engine-features.md | 10 ++++++++
docs/installation-development.md | 16 +++++++++---
docs/installation-production.md | 12 ++++++++-
6 files changed, 84 insertions(+), 22 deletions(-)
diff --git a/README.md b/README.md
index 0dbbeece..0c6f5fba 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@ specifically build for the requirements of community radios.
- [Features](#features)
- [Architecture](#architecture)
- [Installation](#installation)
+ - [Read more](#read-more)
- [About](#about)
- [Resources](#resources)
@@ -47,7 +48,14 @@ To learn more, checkout the [Engine Developer Guide](docs/developer-guide.md) or
- [Installation for Development](docs/installation-development.md)
- [Installation for Production](docs/installation-production.md)
-- [Installation using Docker](docs/installation-docker.md)
+- [Running with Docker](docs/running-docker.md)
+
+
+## Read more
+
+- [Configuration Guide](docs/configuration-guide.md)
+- [Developer Guide](docs/developer-guide.md)
+- [Engine Features](docs/engine-features.md)
## About
diff --git a/docs/configuration-guide.md b/docs/configuration-guide.md
index b2db6480..3e66aba4 100644
--- a/docs/configuration-guide.md
+++ b/docs/configuration-guide.md
@@ -27,6 +27,7 @@ This page goes into detail on what is possible to configure within the engine.
- [Install: I don't want to install all Liquidsoap Audio plugins. How?](#install-i-dont-want-to-install-all-liquidsoap-audio-plugins-how)
- [In the Liquidsoap Logs I get 'Error when starting output output_lineout_0: Failure("Error while setting open_pcm: Device or resource busy")!'. What does it mean?](#in-the-liquidsoap-logs-i-get-error-when-starting-output-output_lineout_0-failureerror-while-setting-open_pcm-device-or-resource-busy-what-does-it-mean)
- [How can I find the audio device IDs, required for settings in engine.ini?](#how-can-i-find-the-audio-device-ids-required-for-settings-in-engineini)
+ - [Read more](#read-more)
<!-- /TOC -->
@@ -211,4 +212,15 @@ Well, this is - at least for me - a hard one. I could not manage to find correct
```
or
- * invest in better hardware
\ No newline at end of file
+ * invest in better hardware
+
+
+## Read more
+
+- [Overview](/README.md)
+- [Installation for Development](installation-development.md)
+- [Installation for Production](installation-production.md)
+- [Running with Docker](running-docker.md)
+- [Configuration Guide](configuration-guide.md)
+- [Developer Guide](developer-guide.md)
+- [Engine Features](engine-features.md)
diff --git a/docs/developer-guide.md b/docs/developer-guide.md
index 319e9b0d..4cd329b8 100644
--- a/docs/developer-guide.md
+++ b/docs/developer-guide.md
@@ -1,28 +1,29 @@
-# 1. Aura Engine Development Guide
+# Aura Engine Development Guide
This page gives insights on extending Aura Engine internals or through the API.
<!-- TOC -->
-- [1. Aura Engine Development Guide](#1-aura-engine-development-guide)
- - [1.1. Architecture](#11-architecture)
- - [1.2. Required Data Sources](#12-required-data-sources)
- - [1.3. Provided API Endpoints](#13-provided-api-endpoints)
- - [1.4. Components](#14-components)
- - [1.5. Running the Engine](#15-running-the-engine)
- - [1.6. Default ports used by Engine](#16-default-ports-used-by-engine)
- - [1.7. Debugging Liquidsoap](#17-debugging-liquidsoap)
+- [Aura Engine Development Guide](#aura-engine-development-guide)
+ - [Architecture](#architecture)
+ - [Required Data Sources](#required-data-sources)
+ - [Provided API Endpoints](#provided-api-endpoints)
+ - [Components](#components)
+ - [Running the Engine](#running-the-engine)
+ - [Default ports used by Engine](#default-ports-used-by-engine)
+ - [Debugging Liquidsoap](#debugging-liquidsoap)
+ - [Read more](#read-more)
<!-- /TOC -->
-## 1.1. Architecture
+## Architecture
AURA Engine as part of the AURA Radio Suite uses an modulear architecture
based on a REST API. All external information is retrieved using JSON data-structures.
To get the basic architectural overview, visit the [Aura Meta](https://gitlab.servus.at/autoradio/meta) repository.
-## 1.2. Required Data Sources
+## Required Data Sources
The AURA Project "**Dashboard**" provides the GUI to organize shows, schedules/timelsots
and organize uploads in form of playlists. Those playlists can be organized in timeslots
@@ -46,7 +47,7 @@ to be played and its meta-data:
More information you can find here: <https://gitlab.servus.at/autoradio/meta/blob/master/api-definition.md>
-## 1.3. Provided API Endpoints
+## Provided API Endpoints
**Soundserverstate:** Returns true and false values of the internal In- and Outputs
@@ -58,7 +59,7 @@ More information you can find here: <https://gitlab.servus.at/autoradio/meta/blo
/api/v1/trackservice/
-## 1.4. Components
+## Components
**aura.py**: It is the server which is connected to the external programme source (e.g. aura steering and tank), to liquidsoap and is listening for redis pubsub messages. This precious little server is telling liquidsoap what to play and when.
@@ -68,7 +69,7 @@ More information you can find here: <https://gitlab.servus.at/autoradio/meta/blo
**Liquidsoap**: The heart of AuRa Engine. It uses the built in mixer, to switch between different sources. It records everything and streams everything depending on your settings in aura.ini.
-## 1.5. Running the Engine
+## Running the Engine
Aura Engine is consisting of two components: The Python Engine and Liquidsoap Core.
@@ -83,7 +84,7 @@ It's important to start both components in the correct order:
./run.sh lqs
-## 1.6. Default ports used by Engine
+## Default ports used by Engine
Aura Engine requires a number of ports for internal and external communication.
@@ -94,7 +95,7 @@ Those are the default port numbers:
* `5000` ... Svelte development mode; dynamically uses some other port if occupied
-## 1.7. Debugging Liquidsoap
+## Debugging Liquidsoap
Connect to Liquidsoap via Telnet
@@ -119,3 +120,14 @@ Set the volume of mixer `input 0` to `100%`
Push some audio file to the filesystem `queue 0`
in_filesystem_0.push /path/to/your/file.mp3
+
+
+## Read more
+
+- [Overview](/README.md)
+- [Installation for Development](installation-development.md)
+- [Installation for Production](installation-production.md)
+- [Running with Docker](running-docker.md)
+- [Configuration Guide](configuration-guide.md)
+- [Developer Guide](developer-guide.md)
+- [Engine Features](engine-features.md)
diff --git a/docs/engine-features.md b/docs/engine-features.md
index 2a724c31..01f36572 100644
--- a/docs/engine-features.md
+++ b/docs/engine-features.md
@@ -171,3 +171,13 @@ schemas:
* `/app/trackservice` ................. Web Application for displaying the Track-Service
* `/app/clock` ........................ Web Application for displaying the studio clock
+
+## Read more
+
+- [Overview](/README.md)
+- [Installation for Development](installation-development.md)
+- [Installation for Production](installation-production.md)
+- [Running with Docker](running-docker.md)
+- [Configuration Guide](configuration-guide.md)
+- [Developer Guide](developer-guide.md)
+- [Engine Features](engine-features.md)
diff --git a/docs/installation-development.md b/docs/installation-development.md
index aab0ff46..8dbd3af0 100644
--- a/docs/installation-development.md
+++ b/docs/installation-development.md
@@ -103,7 +103,7 @@ This includes the Liquidsoap audio engine, but does not start the API server.
./run.sh
```
-**Run the Engine Core only**
+**Run the Engine Core and Liquidsoap separately**
This requires to start the Liquidsoap component within some other terminal. This is helpful for
debugging purposes.
@@ -119,7 +119,6 @@ debugging purposes.
```shell
./run.sh lqs
- ./run.sh api
```
**Run the Engine API**
@@ -127,13 +126,24 @@ debugging purposes.
This requires to start the core component in another terminal.
```shell
- ./run.sh lqs
./run.sh api
```
In development mode Engine uses the default [Flask](https://palletsprojects.com/p/flask/) web server.
Please be careful not to use this type of server in your production environment.
+Check out more ways of running the engine in the [Developer Guide](docs/developer-guide.md).
+
## Logging
All Engine logs for development can be found under `./logs`.
+
+## Read more
+
+- [Overview](/README.md)
+- [Installation for Development](installation-development.md)
+- [Installation for Production](installation-production.md)
+- [Running with Docker](running-docker.md)
+- [Configuration Guide](configuration-guide.md)
+- [Developer Guide](developer-guide.md)
+- [Engine Features](engine-features.md)
diff --git a/docs/installation-production.md b/docs/installation-production.md
index e9e856ba..1c849ead 100644
--- a/docs/installation-production.md
+++ b/docs/installation-production.md
@@ -228,4 +228,14 @@ Additionally you'll finde Supervisor specific logs under:
```
`/var/log/supervisor`
-```
\ No newline at end of file
+```
+
+## Read more
+
+- [Overview](/README.md)
+- [Installation for Development](installation-development.md)
+- [Installation for Production](installation-production.md)
+- [Running with Docker](running-docker.md)
+- [Configuration Guide](configuration-guide.md)
+- [Developer Guide](developer-guide.md)
+- [Engine Features](engine-features.md)
--
GitLab