From 86d608cecb56ffa2488eacfda3a43c0fae65cfac Mon Sep 17 00:00:00 2001 From: s-martin Date: Sun, 12 Nov 2023 12:31:13 +0100 Subject: [PATCH] fix some more doc links (#2105) * fix doc links * add a readme to user guide * add readme to developers section * fix links * fix some links * fix links * fix some links * fix links * fix links * fix links * fix links * fix links * add new line --- README.md | 4 +-- documentation/content/developers/README.md | 13 ++++++++++ documentation/content/developers/coreapps.md | 2 +- .../developers/development-environment.md | 5 ++-- documentation/content/developers/docker.md | 2 +- documentation/content/userguide/README.md | 25 +++++++++++++++++++ documentation/content/userguide/audio.md | 18 ++++++------- documentation/content/userguide/concepts.md | 4 +-- .../content/userguide/configuration.md | 4 +-- .../content/userguide/installation.md | 4 +-- documentation/content/userguide/system.md | 2 +- 11 files changed, 59 insertions(+), 24 deletions(-) create mode 100644 documentation/content/developers/README.md create mode 100644 documentation/content/userguide/README.md diff --git a/README.md b/README.md index e45ddaa26..b95b0e8c3 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # RFID Jukebox Version 3 (aka future3) -[![Documentation Status](https://readthedocs.org/projects/rpi-jukebox-rfid/badge/?version=latest)](https://rpi-jukebox-rfid.readthedocs.io/en/latest/?badge=latest) - ## What is this? The exiting, new **Version 3** of the RPi Jukebox RFID. A complete re-write of the Jukebox. @@ -11,7 +9,7 @@ project check out the [documentation of Version 2]( [!NOTE] > This tool will always write a new configurations file. Thus, overwrite the old one (after checking with the user). Any manual modifications to the settings will have to be re-applied diff --git a/documentation/content/developers/development-environment.md b/documentation/content/developers/development-environment.md index 0b271ce38..6d60cdbd4 100644 --- a/documentation/content/developers/development-environment.md +++ b/documentation/content/developers/development-environment.md @@ -16,7 +16,7 @@ developing. 1. Install the latest Pi OS on a SD card. 2. Boot up your Raspberry Pi. -3. [Install](../installation.md) the Jukebox software as if you were building a +3. [Install](../userguide/installation.md) the Jukebox software as if you were building a Phoniebox. You can install from your own fork and feature branch if you wish which can be changed later as well. The original repository will be set as `upstream`. @@ -70,5 +70,4 @@ separately. The MPD usually runs as a service. ## Using Docker container -There is a complete setup -`docker workflow `. +There is a complete [Docker setup](./docker.md). diff --git a/documentation/content/developers/docker.md b/documentation/content/developers/docker.md index f3b9c825f..4384bbf46 100644 --- a/documentation/content/developers/docker.md +++ b/documentation/content/developers/docker.md @@ -52,7 +52,7 @@ They can be run individually or in combination. To do that, we use ### Linux Make sure you don\'t use `sudo` to run your `docker-compose`. Check out -Docker\'s [post-installation guide](https://docs.docker.com/engine/install/linux-postinstall/] for more information. +Docker\'s [post-installation guide](https://docs.docker.com/engine/install/linux-postinstall/) for more information. ``` bash // Build Images diff --git a/documentation/content/userguide/README.md b/documentation/content/userguide/README.md new file mode 100644 index 000000000..5a822a41f --- /dev/null +++ b/documentation/content/userguide/README.md @@ -0,0 +1,25 @@ +# User Guide + +## Getting started + +* [Installing Phoniebox future3](./installation.md) +* [Update](./update.md) +* [Configuring Phoniebox](./configuration.md) + +## Configuration + +* [Audio](./audio.md) +* [RFID](./rfid.md) +* [Card Database](./card-database.md) +* [Troubleshooting](./troubleshooting.md) + +## Advanced + +* [Bluetooth (and audio buttons)](./bluetooth-audio-buttons.md) +* [Auto Hotspot](./autohotspot.md) +* [Concepts](./concepts.md) +* [System](./system.md) +* [Feature Status](../developers/status.md) +* [Known Issues](../developers/known-issues.md) +* [Developer Reference](../developers) + diff --git a/documentation/content/userguide/audio.md b/documentation/content/userguide/audio.md index fb3271197..d948e1035 100644 --- a/documentation/content/userguide/audio.md +++ b/documentation/content/userguide/audio.md @@ -10,14 +10,14 @@ Stream transfer happens on user input or automatically on the connection of an a This is mainly targeted at Bluetooth Headsets/Speakers. Audio outputs run via PulseAudio and the basic configuration should be easy. -There is a [configuration tool](..developers/coreapps#run_configure_audio.py), +There is a [configuration tool](../developers/coreapps.md#run_configure_audio.py), to setup the configuration for the Jukebox Core App. To set up the audio 1. Follow the setup steps according to your sound card 2. Check that the sound output works [as described below](audio.md#checking-system-sound-output) -3. Run the the tool [run_configure_audio](developers/coreapps.md#run_configure_audio.py) +3. Run the the tool [run_configure_audio](../developers/coreapps.md#run_configure_audio.py) 4. [Fine-tune audio parameters](audio.md#additional-options) ## Checking system sound output @@ -99,7 +99,7 @@ Rerun the config tool to register the Bluetooth device with the Jukebox core app For other audio configuration options, please look at the `jukebox.yaml` for now. -Directly edit `jukebox.yaml` following the steps: [Best practice procedure](.md#best-practice-procedure). +Directly edit `jukebox.yaml` following the steps: [Best practice procedure](configuraton.md#best-practice-procedure). ## Developer Information @@ -118,21 +118,21 @@ $ pactl list sinks short Which means we can put any of these as sink into the jukebox configuration file (if there is any need). Mono down mix is enabled by the module `module-remap-sink` -for which documentation and an example can be found [here](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#module-remap-sink>). +for which documentation and an example can be found [here](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#module-remap-sink). -The equalizer is the PulseAudio module `module-ladspa-sink` with the [corresponding documentation](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#module-ladspa-sink>). +The equalizer is the PulseAudio module `module-ladspa-sink` with the [corresponding documentation](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/Modules/#module-ladspa-sink). This in turn loads a [LADSPA plugin](https://www.ladspa.org/). -The LADSPA plugin in the `Eq10X2` plugin of the [CAPS Library](http://quitte.de/dsp/caps.html#Eq10>). The CAPS library is available as linux package `caps`. +The LADSPA plugin in the `Eq10X2` plugin of the [CAPS Library](http://quitte.de/dsp/caps.html#Eq10). The CAPS library is available as linux package `caps`. This is the same plugin which is used in the -[equalizer for pure ALSA](https://github.com/raedwulf/alsaequal>) +[equalizer for pure ALSA](https://github.com/raedwulf/alsaequal) configurations which is part of the linux package `libasound2-plugin-equal`. You are, of course, free to modify the PulseAudio configuration to your needs. References -1. [PulseAudio Documentation](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User>) -2. [PulseAudio Examples](https://wiki.archlinux.org/title/PulseAudio/Examples>) +1. [PulseAudio Documentation](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User) +2. [PulseAudio Examples](https://wiki.archlinux.org/title/PulseAudio/Examples) In this case, run the configuration tool with below parameter to avoid touching the PulseAudio configuration file. diff --git a/documentation/content/userguide/concepts.md b/documentation/content/userguide/concepts.md index 509f474fc..70f285973 100644 --- a/documentation/content/userguide/concepts.md +++ b/documentation/content/userguide/concepts.md @@ -18,10 +18,10 @@ Why should you care? Because we use the same protocol when triggering actions fr You will find a full list of RPC callable functions in [RPC Command Reference](rpc-command-reference.md) and aliases for convenience in [RPC Command Alias Reference](rpc-command-alias-reference.md). -We also have a tool to send RPC commands to the running Jukebox application: [run_rpc_tool.py](src/jukebox/run_rpc_tool.py). +We also have a tool to send RPC commands to the running Jukebox application: [run_rpc_tool.py](../../../src/jukebox/run_rpc_tool.py). ## Publishing Message Queue The Publishing Message Queue is the complementary part to the RPC where the core application publishes its status and status updates. As a user, you need not worry about it. -If you want to interact with the Jukebox from your own application, this is where you get the current state from. Details about the protocol can be found here (TBD). A sniffer tool exists which listens and prints the incoming status messages: [run_publicity_sniffer.py](src/jukebox/run_rpc_tool.py). +If you want to interact with the Jukebox from your own application, this is where you get the current state from. Details about the protocol can be found here (TBD). A sniffer tool exists which listens and prints the incoming status messages: [run_publicity_sniffer.py](../../../src/jukebox/run_rpc_tool.py). diff --git a/documentation/content/userguide/configuration.md b/documentation/content/userguide/configuration.md index d23cce01f..2aaa3184b 100644 --- a/documentation/content/userguide/configuration.md +++ b/documentation/content/userguide/configuration.md @@ -9,8 +9,8 @@ Don't fear (overly), they contain commentaries. For several aspects we have :ref:`developer/coreapps:Configuration Tools` and detailed guides: -* [Audio Configuration](userguide/audio.md#audio-configuration) -* [RFID Reader Configuration](rfid/basics.md#reader-configuration) +* [Audio Configuration](./audio.md#audio-configuration) +* [RFID Reader Configuration](./rfid/basics.md#reader-configuration) Even after running the tools, certain aspects can only be changed by modifying the configuration files directly. diff --git a/documentation/content/userguide/installation.md b/documentation/content/userguide/installation.md index e84b5de05..ef448e98f 100644 --- a/documentation/content/userguide/installation.md +++ b/documentation/content/userguide/installation.md @@ -9,7 +9,7 @@ Before you can install the Phoniebox software, you need to prepare your Raspberr 1. Connect a Micro SD card to your computer (preferable an SD card with high read throughput) 2. [Download](https://www.raspberrypi.org/software/) - the [Raspberry Pi Imager](https://www.raspberrypi.org/blog/raspberry-pi-imager-imaging-utility/>) and open it + the [Raspberry Pi Imager](https://www.raspberrypi.org/blog/raspberry-pi-imager-imaging-utility/) and open it 3. Select **Raspberry Pi OS Lite (32-bit)** (without desktop environment) as the operating system. future3 does not support 64bit kernels (`aarch64`). You can use the settings menu of the Raspberry Pi Imager to configure SSH and WiFi in a more userfriendly way, or do it manually as described in the next step. In case you already have a 64bit system installed, [you can fix the issue like this](https://github.com/MiczFlor/RPi-Jukebox-RFID/issues/2041>). 4. Select your Micro SD card (your card will be formatted) 5. Click *Write* @@ -82,7 +82,7 @@ cd; GIT_USER='MiczFlor' GIT_BRANCH='future3/develop' bash <(wget -qO- https://ra This will switch directly to the specified feature branch during installation. > [!NOTE] -> For all branches *except* the current Release, you will need to build the Web App locally on the Pi. This is not part of the installation process due to memory limitation issues. See [Steps to install](developers/development-environment#steps-to-install) +> For all branches *except* the current Release, you will need to build the Web App locally on the Pi. This is not part of the installation process due to memory limitation issues. See [Steps to install](../developers/development-environment.md#steps-to-install) If you suspect an error you can monitor the installation-process with diff --git a/documentation/content/userguide/system.md b/documentation/content/userguide/system.md index a9e4a162e..5b1ce5c0c 100644 --- a/documentation/content/userguide/system.md +++ b/documentation/content/userguide/system.md @@ -8,7 +8,7 @@ The system consists of 2. [PulseAudio](system.md#pulseaudio) for flexible audio output support 3. [Jukebox Core Service](system.md#jukebox-core-service) for controlling MPD and PulseAudio and providing all the features 4. [Web UI](system.md#web-ui) which is served through an Nginx web server -5. A set of [Configuration Tools](../developer/coreapps.md#configuration-tools) and a set of [Developer Tools](../developer/coreapps.md#developer-tools) +5. A set of [Configuration Tools](../developers/coreapps.md#configuration-tools) and a set of [Developer Tools](../developers/coreapps.md#developer-tools) .. note:: The default install puts everything into the folder `/home/pi/RPi-Jukebox-RFID`. Another folder might work, but is certainly not tested. Things are installed for the default user `pi`. Again,