Add markdown linting (#2284)

* fix docs * add markdown action * use different action * change linter * add checkout * change globs * change wildcard * Aktualisieren von markdown_v3.yml * fix ignore * comment ignore * change version * use master * new action used for linting * Fix config * Remove ignore * Ignore docstring dir * ignore GitHub * Aktualisieren von markdown_v3.yml * use dot true * Aktualisieren von markdown_v3.yml * Use new action * Fix continue-on-error * Remove unnecessary code * Add markdownlint config * Rename . markdownlint-cli2.yaml to .markdownlint-cli2.yaml * Use config file * Simplify globs * Use globs and ignore in config file * Ignore $ errors * Ignore src and .github * Use only config file * Fix general glob * Ignore inline html * Disable MD010 * Fix language * dont warn trailing punctuation * fix warnings * fix a warning * reduce ignore * fix warnings * fail check, if markdownlint fails * add runner script and hook * Update documentation/builders/components/power/onoff-shim.md Co-authored-by: Alvin Schiller <[email protected]> * Update playlists-livestreams-podcasts.md * add documentation for documentation with md * get rid of docker * fix comments * incorporate comments * Update documentation/developers/documentation.md Co-authored-by: Alvin Schiller <[email protected]> * check, if cmd does not exisr --------- Co-authored-by: Alvin Schiller <[email protected]>
MiczFlor · Mar 21, 2024 · c3b622c · c3b622c
1 parent 2b5ef6e
commit c3b622c
Show file tree

Hide file tree

Showing 29 changed files with 492 additions and 93 deletions.
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
@@ -9,6 +9,9 @@
 #   Note: This only checks the modified files
 # - docs build of if any python file is staged
 #   Note: This builds the entire documentation if a changed file goes into the documentation
+# - Markdownlint if any markdown file is staged
+#   Note: This checks all markdown files as configured in .markdownlint-cli2.yaml
+
 #
 # If there are problem with this script, commit may still be done with
 # git commit --no-verify
@@ -40,6 +43,20 @@ fi
 
 code=$(( flake8_code + doc_code ))
 
+# Pass all staged markdown files through markdownlint-cli2
+MD_FILES="$(git diff --diff-filter=d --staged --name-only -- **/*.md)"
+markdownlint_code=0
+if [[ -n $MD_FILES ]]; then
+  echo -e "\n**************************************************************"
+  echo "Modified Markdown files. Running markdownlint-cli2 ... "
+  echo -e "**************************************************************\n"
+  ./run_markdownlint.sh
+  markdownlint_code=$?
+  echo "Markdownlint-cli2 return code: $markdownlint_code"
+fi
+
+code=$(( flake8_code + doc_code + markdownlint_code))
+
 if [[ code -gt 0 ]]; then
   echo -e "\n**************************************************************"
   echo -e "ERROR(s) during pre-commit checks. Aborting commit!"

diff --git a/.github/ISSUE_TEMPLATE/bug_template.md b/.github/ISSUE_TEMPLATE/bug_template.md
@@ -33,7 +33,6 @@ Please post here the output of 'tail -n 500 /var/log/syslog' or 'journalctl -u m
 i.e. `find logfiles at https://paste.ubuntu.com/p/cRS7qM8ZmP/`
 -->
 
-
 ## Software
 
 ### Base image and version
@@ -59,7 +58,6 @@ the following command will help with that
 i.e. `scripts/installscripts/buster-install-default.sh`
 -->
 
-
 ## Hardware
 
 ### RaspberryPi version

diff --git a/.github/workflows/markdown_v3.yml b/.github/workflows/markdown_v3.yml
@@ -0,0 +1,28 @@
+name: Markdown Linting
+
+on:
+  push:
+    branches:
+        - 'future3/**'
+    paths:
+        - '**.md'
+  pull_request:
+    branches:
+        - 'future3/**'
+    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,52 @@
+#
+# 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
+
+# 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:
+  - "documentation/developers/docstring/*"
+  - "src/**"
+
+# 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/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1,14 +1,14 @@
+# Contributor Covenant Code of Conduct
 
-Dear Phonieboxians,
-
-As the Phoniebox community is growing, somebody suggested a pull request with the below document. I was hesitant to include it right away, but at the same time I thought: it might be good to have some kind of document to formulate the foundation this project is built on. To tell you the truth, this document is not it. However, it is a start and I thought: why not open this in the spirit of open source, sharing and pull requests and see if and how you or you or you want to change or add parts of this very *standard and corporate* document. Like most of you, I also have a small kid and my time is scarce, I might find some time though to add a bit.
-
-All the best, Micz
+> [!NOTE]
+> Dear Phonieboxians,
+>
+> As the Phoniebox community is growing, somebody suggested a pull request with the below document. I was hesitant to include it right away, but at the same time I thought: it might be good to have some kind of document to formulate the foundation this project is built on. To tell you the truth, this document is not it. However, it is a start and I thought: why not open this in the spirit of open source, sharing and pull requests and see if and how you or you or you want to change or add parts of this very *standard and corporate* document. Like most of you, I also have a small kid and my time is scarce, I might find some time though to add a bit.
+>
+> All the best, Micz
 
 2018-08-21
 
-# Contributor Covenant Code of Conduct
-
 This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
 
 ## Our Pledge

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -45,15 +45,16 @@ as local, temporary scratch areas.
 
 Contributors have played a bigger role over time to keep Phoniebox on the edge of innovation :)
 
-Our goal is to make it simple for you to contribute changes that improve functionality in your specific environment. 
-To achieve this, we have a set of guidelines that we kindly request contributors to adhere to. 
+Our goal is to make it simple for you to contribute changes that improve functionality in your specific environment.
+To achieve this, we have a set of guidelines that we kindly request contributors to adhere to.
 These guidelines help us maintain a streamlined process and stay on top of incoming contributions.
 
 To report bug fixes and improvements, please follow the steps outlined below:
+
 1. For bug fixes and minor improvements, simply open a new issue or pull request (PR).
 2. If you intend to port a feature from Version 2.x to future3 or wish to implement a new feature, we recommend reaching out to us beforehand.
-   - In such cases, please create an issue outlining your plans and intentions.
-   - We will ensure that there are no ongoing efforts on the same topic.
+   * In such cases, please create an issue outlining your plans and intentions.
+   * We will ensure that there are no ongoing efforts on the same topic.
 
 We eagerly await your contributions! You can review the current [feature list](documentation/developers/status.md) to check for available features and ongoing work.
 
@@ -108,7 +109,7 @@ Run the checks below on the code. Fix those issues! Or you are running in delays
 We provide git hooks for those checks for convenience. To activate
 
 ~~~bash
-cp .githooks/pre-commit` .git/hooks/.
+cp .githooks/pre-commit .git/hooks/.
 ~~~
 
 ### Python Code
@@ -152,7 +153,7 @@ to detect in advance.
 
 If the code change results in a test failure, we will make our best effort to
 correct the error. If a fix cannot be determined and committed within 24 hours
-of its discovery, the commit(s) responsible _may_ be reverted, at the
+of its discovery, the commit(s) responsible *may* be reverted, at the
 discretion of the committer and Phonie maintainers.
 The original contributor will be notified of the revert.
 
@@ -163,7 +164,7 @@ The original contributor will be notified of the revert.
 
 ## Guidelines
 
-* Phoniebox runs on Raspberry Pi OS. 
+* Phoniebox runs on Raspberry Pi OS.
 * Minimum python version is currently **Python 3.9**.
 
 ## Additional Resources

diff --git a/documentation/README.md b/documentation/README.md
@@ -42,7 +42,7 @@ project check out the [documentation of Version 2](https://github.com/MiczFlor/R
 Version 3 has reached a mature state and will soon be the default version.
 However, some features may still be missing. Please check the [Feature Status](./developers/status.md), if YOUR feature is already implemented.
 
-> [!NOTE] 
+> [!NOTE]
 > If version 3 has all the features you need, we recommend using Version 3.
 
 If there is a feature missing, please open an issue.

diff --git a/documentation/builders/audio.md b/documentation/builders/audio.md
@@ -24,6 +24,7 @@ to setup the configuration for the Jukebox Core App.
 
 Run the following steps in a console:
 
+<!-- markdownlint-disable MD010 -->
 ```bash
 # Check available PulseAudio sinks
 $ pactl list sinks short
@@ -45,6 +46,7 @@ $ paplay /usr/share/sounds/alsa/Front_Center.wav
 # This must also work when using an ALSA device
 $ aplay /usr/share/sounds/alsa/Front_Center.wav
 ```
+<!-- markdownlint-restore -->
 
 You can also try different PulseAudio sinks without setting the default sink. In this case the volume is the last used
 volume level for this sink:
@@ -86,6 +88,7 @@ Pairing successful
 ....
 [PowerLocus Buddy]# exit
 ```
+
 If `bluetoothctl` has trouble to execute due to permission issue, try `sudo bluetoothctl`.
 
 Wait for a few seconds and then with `$ pactl list sinks short`, check wether the Bluetooth device shows up as an output.

diff --git a/documentation/builders/autohotspot.md b/documentation/builders/autohotspot.md
@@ -7,11 +7,12 @@ The Auto-Hotspot function enables the Jukebox to switch its connection between a
 
 ## How to connect
 
-When the Jukebox cannot connect to a known WiFi, it will automatically create a hotspot. 
+When the Jukebox cannot connect to a known WiFi, it will automatically create a hotspot.
 You can connect to this hotspot using the password set during installation.
 Afterwards, you can access the Web App or connect via SSH as before, using the IP from the configuration.
 
 The default configuration is
+
 ``` text
 * SSID              : Phoniebox_Hotspot_<hostname>
 * Password          : PlayItLoud!
@@ -23,8 +24,7 @@ The default configuration is
 
 Auto-Hotspot can be enabled or disabled using the Web App or RPC Commands.
 
-> [!NOTE]
-> Disabling the Auto-Hotspot will run the WiFi check again and maintain the last connection state until reboot.
+Disabling the Auto-Hotspot will run the WiFi check again and maintain the last connection state until reboot.
 
 > [!IMPORTANT]
 > If you disable this feature, you will lose access to the Jukebox if you are not near a known WiFi after reboot!
@@ -34,11 +34,13 @@ Auto-Hotspot can be enabled or disabled using the Web App or RPC Commands.
 ### AutoHotspot functionality is not working
 
 Check the `autohotspot.service` status
+
 ``` bash
 sudo systemctl status autohotspot.service
 ```
 
 and logs
+
 ``` bash
 sudo journalctl -u autohotspot.service -n 50
 ```
@@ -52,12 +54,13 @@ Check your WiFi configuration.
 ### You need to add a new WiFi network to the Raspberry Pi
 
 #### Using the command line
+
 Connect to the hotspot and open a terminal. Use the [raspi-config](https://www.raspberrypi.com/documentation/computers/configuration.html#wireless-lan) tool to add the new WiFi.
 
 ## Resources
 
 * [Raspberry Connect - Auto WiFi Hotspot Switch](https://www.raspberryconnect.com/projects/65-raspberrypi-hotspot-accesspoints/158-raspberry-pi-auto-wifi-hotspot-switch-direct-connection)
 * [Raspberry Pi - Configuring networking](https://www.raspberrypi.com/documentation/computers/configuration.html#using-the-command-line)
-* [dhcpcd / wpa_supplicant]()
-    * [hostapd](http://w1.fi/hostapd/)
-    * [dnsmasq](https://thekelleys.org.uk/dnsmasq/doc.html)
+* dhcpcd / wpa_supplicant
+  * [hostapd](http://w1.fi/hostapd/)
+  * [dnsmasq](https://thekelleys.org.uk/dnsmasq/doc.html)
diff --git a/documentation/builders/components/power/onoff-shim.md b/documentation/builders/components/power/onoff-shim.md
@@ -9,7 +9,7 @@ To install the software, open a terminal and type the following command to run t
 > [!NOTE]
 > The installation will ask you a few questions. You can safely answer with the default response.
 
-```
+```bash
 curl https://get.pimoroni.com/onoffshim | bash
 ```
 
@@ -28,9 +28,8 @@ The OnOff SHIM comes with a 12-PIN header which needs soldering. If you want to
 | GPLCLK0        | 7         | 7                | GPIO4        |
 | GPIO17         | 11        | 11               | GPIO17       |
 
-* More information can be found here: https://pinout.xyz/pinout/onoff_shim
+* More information can be found here: <https://pinout.xyz/pinout/onoff_shim>
 
 ## Assembly options
 
-![](https://cdn.review-images.pimoroni.com/upload-b6276a310ccfbeae93a2d13ec19ab83b-1617096824.jpg?width=640)
-
+![OnOffShim soldered on a Raspberry Pi](https://cdn.review-images.pimoroni.com/upload-b6276a310ccfbeae93a2d13ec19ab83b-1617096824.jpg?width=640)
diff --git a/documentation/builders/components/soundcards/hifiberry.md b/documentation/builders/components/soundcards/hifiberry.md
@@ -19,7 +19,6 @@ If you know you HifiBerry Board identifier, you can run the script as a 1-liner
 
 If you like to disable your HiFiberry Sound card and enable onboard sound, run the following command
 
-
 ```bash
 ./setup_hifiberry.sh disable
 ```

diff --git a/documentation/builders/configuration.md b/documentation/builders/configuration.md
@@ -27,9 +27,10 @@ $ ./run_jukebox.sh
 # Restart the service
 $ systemctl --user start jukebox-daemon
 ```
-To try different configurations, you can start the Jukebox with a custom config file. 
+
+To try different configurations, you can start the Jukebox with a custom config file.
 This could be useful if you want your Jukebox to only allow a lower volume when started
-at nighttime, signaling it's time to go to bed. :-) 
+at nighttime, signaling it's time to go to bed. :-)
 The path to the custom config file must be either absolute or relative to the folder `src/jukebox/`.
 
 ```bash

diff --git a/documentation/builders/event-devices.md b/documentation/builders/event-devices.md
@@ -1,6 +1,7 @@
 # Event devices
 
 ## Background
+
 Event devices are generic input devices that are exposed in `/dev/input`.
 This includes USB peripherals (Keyboards, Controllers, Joysticks or Mouse) as well as potentially bluetooth devices.
 
@@ -23,6 +24,7 @@ modules:
 ```
 
 And add the following section with the plugin specific configuration:
+
 ``` yaml
 evdev:
   enabled: true
@@ -49,6 +51,7 @@ devices: # list of devices to listen for
           on_press: # Currently only the on_press action is supported
             {rpc_command_definition} # eg `alias: toggle`
 ```
+
 The `{device nickname}` is only for your own orientation and can be choosen freely.
 For each device you need to figure out the `{device_name}` and the `{event_id}` corresponding to key strokes, as indicated in the sections below.
 
@@ -65,7 +68,7 @@ for device in devices:
 
 The output could be in the style of:
 
-```
+```text
 /dev/input/event1    Dell Dell USB Keyboard   usb-0000:00:12.1-2/input0
 /dev/input/event0    Dell USB Optical Mouse   usb-0000:00:12.0-2/input0
 ```
@@ -96,8 +99,10 @@ for event in dev.read_loop():
   if event.type == ecodes.EV_KEY:
     print(categorize(event))
 ```
+
 The output could be of the form:
-```
+
+```text
 device /dev/input/event1, name "DragonRise Inc.   Generic   USB  Joystick  ", phys "usb-3f980000.usb-1.2/input0"
 key event at 1672569673.124168, 297 (BTN_BASE4), down
 key event at 1672569673.385170, 297 (BTN_BASE4), up
@@ -114,7 +119,6 @@ Look for entries like `No callback registered for button ...`.
 
 The RPC command follows the regular RPC command rules as defined in the [following documentation](./rpc-commands.md).
 
-
 ## Full example config
 
-A complete configuration example for a USB Joystick controller can be found in the [examples](../../resources/default-settings/evdev.example.yaml).
+A complete configuration example for a USB Joystick controller can be found in the [examples](../../resources/default-settings/evdev.example.yaml).