Add markdownlint config and action for V2 (#2369)

* fix markdown errors * add markdownlint action and config * fix action * rename config file * fix ignore paths * fix warnings * disable MD033 and MD045 locally
MiczFlor · May 12, 2024 · a889ba7 · a889ba7
1 parent f3b4b20
commit a889ba7
Show file tree

Hide file tree

Showing 8 changed files with 154 additions and 49 deletions.
diff --git a/.github/workflows/markdown.yml b/.github/workflows/markdown.yml
@@ -0,0 +1,29 @@
+name: Markdown Linting
+
+on:
+  push:
+    branches-ignore:
+        - 'future3/**'
+    paths:
+        - '**.md'
+  pull_request:
+    branches:
+        - develop
+        - master
+    paths:
+        - '**.md'
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Linting markdown
+      uses: DavidAnson/markdownlint-cli2-action@v15
+      with:
+        config: .markdownlint-cli2.yaml
+      #continue-on-error: true
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
@@ -0,0 +1,56 @@
+#
+# markdownlint-cli2 configuration, see https://github.com/DavidAnson/markdownlint-cli2?tab=readme-ov-file#configuration
+#
+
+# rules, see https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+config:
+  line-length: false
+  # ignore dollar signs
+  commands-show-output: false
+  no-trailing-punctuation: false
+  no-duplicate-heading:
+    siblings_only: true
+  # allow some tags we use for formatting
+  no-inline-html:
+    allowed_elements: [ "details", "summary" ]
+
+# Include a custom rule package
+#customRules:
+#  - markdownlint-rule-titlecase
+
+# Fix no fixable errors
+fix: false
+
+# Define a custom front matter pattern
+#frontMatter: "<head>[^]*<\/head>"
+
+# Define glob expressions to use (only valid at root)
+globs:
+  - "**.md"
+
+# Define glob expressions to ignore
+ignores:
+  - "htdocs/**"
+
+# Use a plugin to recognize math
+#markdownItPlugins:
+#  -
+#    - "@iktakahiro/markdown-it-katex"
+
+# Additional paths to resolve module locations from
+#modulePaths:
+#  - "./modules"
+
+# Enable inline config comments
+noInlineConfig: false
+
+# Disable progress on stdout (only valid at root)
+noProgress: true
+
+# Use a specific formatter (only valid at root)
+#outputFormatters:
+#  -
+#    - markdownlint-cli2-formatter-default
+
+# Show found files on stdout (only valid at root)
+showFound: true
diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@ Phoniebox is a contactless jukebox for the Raspberry Pi, playing audio files, pl
 
 Another bunch of wonderful designs!
 
-To share your design or see all previous calendars and designs of the community visit the [Phoniebox Gallery](https://github.com/MiczFlor/RPi-Jukebox-RFID/wiki/GALLERY). 
+To share your design or see all previous calendars and designs of the community visit the [Phoniebox Gallery](https://github.com/MiczFlor/RPi-Jukebox-RFID/wiki/GALLERY).
 
 ![The Phoniebox Calendar](https://raw.githubusercontent.com/wiki/MiczFlor/RPi-Jukebox-RFID/img/gallery/calendar/latest-Phoniebox-Calendar.jpg "The Phoniebox Calendar")
 
@@ -189,6 +189,8 @@ These are links to additional items, which will add an individual flavour to you
 Special hardware is now organised in the folder [`components`](components/). If you have new hardware attached to your Phoniebox, please add to this library! It currently contains soundcards, displays, GPIO controls, RFID reader, smarthome integration.
 
 ## Support Phoniebox
+<!-- markdownlint-disable MD033 -->
+<!-- markdownlint-disable MD045 -->
 
 <a href="https://www.buymeacoffee.com/MiczFlor" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/guidelines/download-assets-sm-2.svg"></a>
 
@@ -211,6 +213,8 @@ See the Phoniebox code in action, watch this video and read the blog post from [
 
 A new video screencast about
 
+<!-- markdownlint-restore -->
+
 **What makes this Phoniebox easy to install and use:**
 
 * Runs on all Raspberry Pi models (1, 2, 3 and 4) and [Raspberry Zero](https://github.com/MiczFlor/RPi-Jukebox-RFID/issues/15).
@@ -243,7 +247,6 @@ See innovation, upcycling and creativity in the [Phoniebox Gallery](https://gith
 ![Caption](https://raw.githubusercontent.com/wiki/MiczFlor/RPi-Jukebox-RFID/img/gallery/KingKahn-20180101-Jukebox-01-h90.jpg)
 ![Caption](https://raw.githubusercontent.com/wiki/MiczFlor/RPi-Jukebox-RFID/img/gallery/hailogugo-20171222-h90-01.jpg)
 
-
 ## Sustainability
 
 You might be surprised how easy and affordable you can get a RaspberryPi or an "appropriate" housing for your Phoniebox **second hand**. Think about the planet before you buy a new one.

diff --git a/ci/README.md b/ci/README.md
@@ -11,35 +11,42 @@ This is a work in progress so expect things to fail or being flaky.
 * Flash its sd card with **Raspberry Pi OS lite**
 * use raspi-config to resize the filesystem to the whole sd card (menu: 7 -> A1)
 * install some tools and reboot:
-```bash
+
+    ```bash
       sudo apt-get update
       sudo apt-get -y dist-upgrade
       sudo apt-get -y install docker.io git
       sudo gpasswd -a pi docker
       sudo reboot
-```
+    ```
+
 * login to your RPi
 * clone the repo and cd into its local clone:
-```bash
+
+    ```bash
       cd /home/pi/
       # optional: change to your fork appropriately
       git clone https://github.com/MiczFlor/RPi-Jukebox-RFID.git
       cd RPi-Jukebox-RFID/
       # optional: switch to another branch
       git checkout <branch_name>
-```
+    ```
+
 * build the docker image:
+
     ```bash
     docker build -t rpi-jukebox-rfid:debian-latest -f ci/Dockerfile.debian --platform=linux/arm/v7 --target=code .
     ```
-    * additional arguments
-        * for builds
-          - on normal PCs use `--platform=linux/amd64`
-          - on a raspberry pi use `--platform=linux/arm/v7`
-        * to use a different debian version as base add parameter `--build-arg="DEBIAN_CODENAME=<code_name>"` (<code_name> = e.g. buster, bullseye, ...).
+
+  * additional arguments
+    * for builds
+      * on normal PCs use `--platform=linux/amd64`
+      * on a raspberry pi use `--platform=linux/arm/v7`
+    * to use a different debian version as base add parameter `--build-arg="DEBIAN_CODENAME=<code_name>"` (<code_name> = e.g. buster, bullseye, ...).
 
 * get something to drink or eat
 * run the freshly built docker image and start testing. For example:
+
     ```bash
       docker run --rm -ti rpi-jukebox-rfid:debian-latest /bin/bash
       cd /home/pi/
@@ -48,12 +55,14 @@ This is a work in progress so expect things to fail or being flaky.
       bash GIT_URL=https://github.com/MiczFlor/RPi-Jukebox-RFID.git GIT_BRANCH=main install-jukebox.sh
     ```
 
-    NOTE: Get familiar with docker and its flags - `--rm` for example will remove the
-          container after you log out of it and all changes will be lost.
+    > [!NOTE]
+    > Get familiar with docker and its flags - `--rm` for
+    > example will remove the
+    > container after you log out of it and all changes will be lost.
 
 ### mount hosts code as volume
 
-The created image now contains all the code in the directory `/code` - if you do not want to rebuild the image after each code-change you can 'mount' the RPi's code version into the container. 
+The created image now contains all the code in the directory `/code` - if you do not want to rebuild the image after each code-change you can 'mount' the RPi's code version into the container.
 Add `-w /code -v $PWD:/code` to the `docker run` parameter.
 
 In that way every change to the code in the container will be available on the RPi as well as vice versa.
diff --git a/components/controls/buttons-bluetooth-headphone/README.md b/components/controls/buttons-bluetooth-headphone/README.md
@@ -1,15 +1,15 @@
-## Control Phoniebox via Buttons from Bluetooth Headset
+# Control Phoniebox via Buttons from Bluetooth Headset
 
 Many bluetooth headsets or bluetooth speaker sets have buttons for controlling the music stream. **Let's make use of them!**
 This component provides support for controlling your Phoniebox through these buttons on your bluetooth headset (or speaker set).
 
-### Installation
+## Installation
 
 1. Make sure your bluetooth headset is connected to the Phoniebox. Follow the instructions in the [Wiki](https://github.com/MiczFlor/RPi-Jukebox-RFID/wiki/Connecting_Bluetooth_device_to_Phoniebox).
 2. Execute `$ ./install-bt-buttons.sh. It will ask you to identify your headset and set up appropriate user rights, and registers the script as a service. It should work immediatly. In case of doubt, reboot.
     - If later changing the headset, re-run `$ ./register-device.py`. Reboot or restart the service with `sudo systemctl restart phoniebox-bt-buttons.service`
 
-### Supported Buttons
+## Supported Buttons
 
 Out-of-the box support is included for the following buttons
 
@@ -21,7 +21,7 @@ Key codes are standarized and so it should also work with your headphones. If yo
 
 *Note:* Volume up/down is inherently supported by the bluetooth protocol. There is no need to handle these by this script.
 
-### On Connect / On Disconnect
+## On Connect / On Disconnect
 
 If the feature [bluetooth-sink-switch](../../bluetooth-sink-switch) is enabled, the script automatically switches the audio stream to headphones / regular speakers on bluetooth connect / disconnect  respectivly. Playback state (play/pause) is retained.
 
@@ -34,16 +34,16 @@ You can **customize** the behaviour by editing the functions
 
 where `mpd_support` indicates wether the bt-sink-switch-feature is enabled.
 
-### Troubleshooting
+## Troubleshooting
 
 This feature has been tested with PowerLocus Buddy and Sennheiser Momentum M2 AEBT headphones.
 
-#### Preparation
+### Preparation
 
 - Stop the service `$ sudo systemctl stop phoniebox-bt-buttons.service`
 - Start the script in a command line with debug option `$ ./bt-buttons.py debug`
 
-#### Check that correct bluetooth device is found
+### Check that correct bluetooth device is found
 
 - Run the [preparatory steps](#preparation)
 - Check headset is connected and listed as input event device with `$ cat /proc/bus/input/devices`. Note the device name.
@@ -57,7 +57,7 @@ This feature has been tested with PowerLocus Buddy and Sennheiser Momentum M2 AE
 
 - If you see discrepancies, re-run `$ ./register-device.py`(see above)
 
-#### Add key codes / change actions
+### Add key codes / change actions
 
 - Run the [preparatory steps](#preparation)
 - Press the buttons on the headset and check for these debug outputs. Note down the keycode. The **163** is the keycode, you are looking for. Go through all the buttons. Also try short/long press. On my headphones, they result in different keycodes
@@ -78,7 +78,7 @@ This feature has been tested with PowerLocus Buddy and Sennheiser Momentum M2 AE
 
 ~~~
 
-#### Still having trouble?
+### Still having trouble?
 
 Check the basics: test the event input. Make sure the headphones are connected beforehand. Replace event*X* with the event number obtained from `$ cat /proc/bus/input/devices`.
 

diff --git a/components/gpio_control/README.md b/components/gpio_control/README.md
@@ -62,8 +62,9 @@ However, a button has more parameters than these. In the following comprehensive
 
 > [!IMPORTANT]
 > Since v2.8.0 the behavior of `hold_mode` `SecondFunc` and `SecondFuncRepeat` has changed. The secondary function is no longer triggered additionally to the primary function.
-> Now its called exclusively if `hold_time` is reached. The primary function will only be triggered if the button is pressed shorter then `hold_time`! 
+> Now its called exclusively if `hold_time` is reached. The primary function will only be triggered if the button is pressed shorter then `hold_time`!
 > Existing configurations may need to adapt to this.
+
 * **hold_mode**: Specifies what shall happen if the button is held pressed for longer than `hold_time`:
   * `None` (Default): Nothing special will happen.
   * `Repeat`: The configured `functionCall` is instantly called and repeatedly after each `hold_time` interval.
@@ -87,7 +88,8 @@ However, a button has more parameters than these. In the following comprehensive
 * **bouncetime**: This is a setting of the GPIO library to limit bouncing effects during button usage. Default is `500` ms.
 * **antibouncehack**: Despite the integrated bounce reduction of the GPIO library some users may notice false triggers of their buttons (e.g. unrequested / double actions when releasing the button). If you encounter such problems, try setting this to `True` to activate an additional countermeasure.
 
-Note: If you prefer, you may also use `Type: SimpleButton` instead of `Type: Button` - this makes no difference.
+> [!NOTE]
+> If you prefer, you may also use `Type: SimpleButton` instead of `Type: Button` - this makes no difference.
 
 ### ShutdownButton
 
@@ -116,7 +118,7 @@ Again, there are more parameters than these. In the following comprehensive list
 * **iteration_time**: This parameter determines the flashing speed of the LED indicator. Default value is `0.2` seconds.
 * **functionCall**: While the default action is `functionCallShutdown`, you might use this button type even with other functions than system shutdown (again, see [function documentation below](#functions) for a list of available functions).
 
-Furthermore, the following settings can be used as described for the [regular buttons](#doc_button): **pull_up_down**, **edge**, **bouncetime**, **antibouncehack**, **functionCallArgs**
+Furthermore, the following settings can be used as described for the [regular buttons](#button): **pull_up_down**, **edge**, **bouncetime**, **antibouncehack**, **functionCallArgs**
 
 Note that using a ShutdownButton without a LED can also be implemented with a normal button like this:
 
@@ -189,14 +191,16 @@ functionCall2: functionCallVolD
 * **functionCall1**: function called for every rotation step corresponding to rotary direction "clockwise". See below for passed arguments. See [function documentation below](#functions).
 * **functionCall2**: function called for every rotation step corresponding to rotary direction "counter clockwise". See below for passed arguments. See [function documentation below](#functions).
 * **timeBase**: Factor used for calculating the rotation value base on rotation speed, defaults to `0.1`. Use `0` for deactivating rotation speed influence.
-Example: 
- * a single rotation step leads to the value 1 passed to the function. 
- * steady rotation of two to or more steps, leads to the value 1 for the first call and the value 2 for all further calls.
- * speeding up rotation of two to or more steps, leads to the value 1 for the first call, the value 2 for the second, the value 3 for the third and so on.
-* **functionCall1Args**: Arguments for `functionCall1`, defaults to `None`. If defined takes precedence over rotation value. Arguments are ignored, if `functionCall1` does not take any. 
-* **functionCall2Args**: Arguments for `functionCall2`, defaults to `None`. If defined takes precedence over rotation value. Arguments are ignored, if `functionCall1` does not take any. 
+
+  Example:
+  * a single rotation step leads to the value 1 passed to the function.
+  * steady rotation of two to or more steps, leads to the value 1 for the first call and the value 2 for all further calls.
+  * speeding up rotation of two to or more steps, leads to the value 1 for the first call, the value 2 for the second, the value 3 for the third and so on.
+* **functionCall1Args**: Arguments for `functionCall1`, defaults to `None`. If defined takes precedence over rotation value. Arguments are ignored, if `functionCall1` does not take any.
+* **functionCall2Args**: Arguments for `functionCall2`, defaults to `None`. If defined takes precedence over rotation value. Arguments are ignored, if `functionCall1` does not take any.
 
 To also use the push button of the encoder just a button definition:
+
 ```bash
 [Mute]
 enabled: True
@@ -207,7 +211,6 @@ functionCall: functionCallVol0
 
 Note that the old configuration entries PinUp/PinDown and functionCallUp/functionCallDown are deprecated and might stop working in future.
 
-
 ```bash
 [RotarySeekingControl]
 enabled: True
@@ -223,9 +226,9 @@ functionCall2Args: 5
 
 In this example, the encoder will be used to seek for- and backwards by 5 seconds on every rotation step. The rotation value will **NOT** be used in this case as the function args are defined!
 
-
 #### Circuit diagram
-```text 
+
+```text
   .---------------.                      .---------------.
   |               |                      |               |
   |           CLK |----------------------| GPIO 22       |
@@ -255,7 +258,9 @@ Pin: 14
 
 * **Pin**: GPIO number of the LED (mandatory option). Note that you should not attach LEDs to GPIO ports without a matching resistor in line.
 
-Note: If you prefer, you may also use `Type: MPDStatusLED` instead of `Type: StatusLED` - this makes no difference.
+> [!NOTE]
+> If you prefer, you may also use `Type: MPDStatusLED` instead of
+> `Type: StatusLED` - this makes no difference.
 
 ### Further examples
 
@@ -309,6 +314,7 @@ In this example, a short press initiates a short jump forward by customized 5 se
 For jumping backwards, this can be done equivalently (see [function list below](#functions)).
 
 #### Use Buttons to start playlists
+
 To use GPIO-Pins to play music, you can emulate a card scan with the function `functionCallTriggerPlayCardId`. Supply the `cardid` as `functionCallArgs`.
 This behaves like a card scan, so you must link a folder to the id (on first press it will show up in the Web App as new card).
 

diff --git a/components/synchronisation/sync-shared/README.md b/components/synchronisation/sync-shared/README.md
@@ -35,11 +35,11 @@ You may also change the settings in the according files directly.
 
 ### Settings
 
-**{INSTALLATION_ROOT}/settings/sync-shared-enabled**
+#### {INSTALLATION_ROOT}/settings/sync-shared-enabled
 
 Holds the activation state of this feature. Values are "TRUE" or "FALSE"
 
-**{INSTALLATION_ROOT}/settings/sync-shared.conf**
+#### {INSTALLATION_ROOT}/settings/sync-shared.conf
 
 SYNCSHAREDMODE: The mode to access the server files. SSH or MOUNT