fix formatting for md

MiczFlor · Dec 28, 2023 · 3315e15 · 3315e15
1 parent f1bc657
commit 3315e15
Show file tree

Hide file tree

Showing 13 changed files with 207 additions and 206 deletions.
diff --git a/documentation/developers/docstring/README.md b/documentation/developers/docstring/README.md
diff --git a/src/jukebox/components/battery_monitor/batt_mon_i2c_ads1015/__init__.py b/src/jukebox/components/battery_monitor/batt_mon_i2c_ads1015/__init__.py
@@ -35,42 +35,39 @@
 
 
 class battmon_ads1015(BatteryMonitorBase.BattmonBase):
-    '''Battery Monitor based on a ADS1015
+    """Battery Monitor based on a ADS1015
 
-    CAUTION - WARNING
-    ========================================================================
-    Lithium and other batteries are dangerous and must be treated with care.
-    Rechargeable Lithium Ion batteries are potentially hazardous and can
-    present a serious FIRE HAZARD if damaged, defective or improperly used.
-    Do not use this circuit to a lithium ion battery without expertise and
-    training in handling and use of batteries of this type.
-    Use appropriate test equipment and safety protocols during development.
-
-    There is no warranty, this may not work as expected or at all!
-    =========================================================================
+    > [!CAUTION]
+    > Lithium and other batteries are dangerous and must be treated with care.
+    > Rechargeable Lithium Ion batteries are potentially hazardous and can
+    > present a serious **FIRE HAZARD** if damaged, defective or improperly used.
+    > Do not use this circuit to a lithium ion battery without expertise and
+    > training in handling and use of batteries of this type.
+    > Use appropriate test equipment and safety protocols during development.
+    > There is no warranty, this may not work as expected or at all!
 
     This script is intended to read out the Voltage of a single Cell LiIon Battery using a CY-ADS1015 Board:
 
-                                                  3.3V
-                                                   +
-                                                   |
-                                              .----o----.
-                        ___                   |         |  SDA
-              .--------|___|---o----o---------o AIN0    o------
-              |         2MΩ    |    |         |         |  SCL
-              |               .-.   |         | ADS1015 o------
-             ---              | |  ---        |         |
-     Battery  -          1.5MΩ| |  ---100nF   '----o----'
-     2.9V-4.2V|               '-'   |              |
-              |                |    |              |
-             ===              ===  ===            ===
+                                                      3.3V
+                                                       +
+                                                       |
+                                                  .----o----.
+                            ___                   |         |  SDA
+                  .--------|___|---o----o---------o AIN0    o------
+                  |         2MΩ    |    |         |         |  SCL
+                  |               .-.   |         | ADS1015 o------
+                 ---              | |  ---        |         |
+         Battery  -          1.5MΩ| |  ---100nF   '----o----'
+         2.9V-4.2V|               '-'   |              |
+                  |                |    |              |
+                 ===              ===  ===            ===
 
     Attention:
-        - the circuit is constantly draining the battery! (leak current up to: 2.1µA)
-        - the time between sample needs to be a minimum 1sec with this high impedance voltage divider
+    * the circuit is constantly draining the battery! (leak current up to: 2.1µA)
+    * the time between sample needs to be a minimum 1sec with this high impedance voltage divider
           don't use the continuous conversion method!
 
-    '''
+    """
 
     def __init__(self, cfg):
         super().__init__(cfg, logger)

diff --git a/src/jukebox/components/controls/bluetooth_audio_buttons/__init__.py b/src/jukebox/components/controls/bluetooth_audio_buttons/__init__.py
@@ -4,9 +4,9 @@
 
 This effectively does:
 
-    * register a callback with components.volume to get notified when a new sound card connects
-    * if that is a bluetooth device, try opening an input device with similar name using
-    * button listeners are run each in its own thread
+* register a callback with components.volume to get notified when a new sound card connects
+* if that is a bluetooth device, try opening an input device with similar name using
+* button listeners are run each in its own thread
 
 """
 import logging

diff --git a/src/jukebox/components/controls/common/evdev_listener.py b/src/jukebox/components/controls/common/evdev_listener.py
@@ -49,10 +49,8 @@ def _filter_by_device_name(all_devices: List[evdev.InputDevice],
 def find_device(device_name: str, exact_name: bool = True, mandatory_keys: Optional[Set[int]] = None) -> str:
     """Find an input device with device_name and mandatory keys.
 
-    Raises
-
-        #. FileNotFoundError, if no device is found.
-        #. AttributeError, if device does not have the mandatory keys
+    :raise FileNotFoundError: if no device is found.
+    :raise AttributeError: if device does not have the mandatory key
 
     If multiple devices match, the first match is returned
 

diff --git a/src/jukebox/components/gpio/gpioz/core/input_devices.py b/src/jukebox/components/gpio/gpioz/core/input_devices.py
@@ -9,7 +9,8 @@
 All callback handlers are replaced by GPIOZ callback handlers. These are usually configured
 by using the :func:`set_rpc_actions` each input device exhibits.
 
-For examples how to use the devices from the configuration files, see :ref:`userguide/gpioz:Input devices`
+For examples how to use the devices from the configuration files, see
+[../../builders/gpio.md#input-devices](GPIO: Input Devices).
 """
 
 import functools

diff --git a/src/jukebox/components/gpio/gpioz/core/mock.py b/src/jukebox/components/gpio/gpioz/core/mock.py
@@ -19,7 +19,7 @@ def patch_mock_outputs_with_callback():
     This targets to represent the state in the TK GUI.
     Other output devices cannot be represented in the GUI and are silently ignored.
 
-    ..note:: Only for developing purposes!"""
+    > [!NOTE] Only for developing purposes!"""
     gpiozero.LED._write_orig = gpiozero.LED._write
     gpiozero.LED._write = rewrite
     gpiozero.LED.on_change_callback = None

diff --git a/src/jukebox/components/gpio/gpioz/core/output_devices.py b/src/jukebox/components/gpio/gpioz/core/output_devices.py
@@ -11,7 +11,8 @@
 with parameters for this device and optional parameters from another device. Unused/unsupported parameters
 are silently ignored. This is done to reduce the amount of coding required for connectivity functions.
 
-For examples how to use the devices from the configuration files, see :ref:`userguide/gpioz:Output devices`
+For examples how to use the devices from the configuration files, see
+[../../builders/gpio.md#output-devices](GPIO: Output Devices).
 """
 
 from typing import Optional, List

diff --git a/src/jukebox/components/gpio/gpioz/plugin/__init__.py b/src/jukebox/components/gpio/gpioz/plugin/__init__.py
@@ -56,15 +56,15 @@ class ServiceIsRunningCallbacks(CallbackHandler):
     """
     Callbacks are executed when
 
-       * Jukebox app started
-       * Jukebox shuts down
+    * Jukebox app started
+    * Jukebox shuts down
 
     This is intended to e.g. signal an LED to change state.
     This is integrated into this module because:
 
-        * we need the GPIO to control a LED (it must be available when the status callback comes)
-        * the plugin callback functions provide all the functionality to control the status of the LED
-        * which means no need to adapt other modules
+    * we need the GPIO to control a LED (it must be available when the status callback comes)
+    * the plugin callback functions provide all the functionality to control the status of the LED
+    * which means no need to adapt other modules
     """
 
     def register(self, func: Callable[[int], None]):
@@ -76,7 +76,7 @@ def register(self, func: Callable[[int], None]):
         .. py:function:: func(status: int)
             :noindex:
 
-            :param status: 1 if app started, 0 if app shuts down
+        :param status: 1 if app started, 0 if app shuts down
         """
         super().register(func)
 

diff --git a/src/jukebox/components/gpio/gpioz/plugin/connectivity.py b/src/jukebox/components/gpio/gpioz/plugin/connectivity.py
@@ -55,11 +55,11 @@ def register_rfid_callback(device):
 
     Compatible devices:
 
-        - :class:`components.gpio.gpioz.core.output_devices.LED`
-        - :class:`components.gpio.gpioz.core.output_devices.PWMLED`
-        - :class:`components.gpio.gpioz.core.output_devices.RGBLED`
-        - :class:`components.gpio.gpioz.core.output_devices.Buzzer`
-        - :class:`components.gpio.gpioz.core.output_devices.TonalBuzzer`
+    * :class:`components.gpio.gpioz.core.output_devices.LED`
+    * :class:`components.gpio.gpioz.core.output_devices.PWMLED`
+    * :class:`components.gpio.gpioz.core.output_devices.RGBLED`
+    * :class:`components.gpio.gpioz.core.output_devices.Buzzer`
+    * :class:`components.gpio.gpioz.core.output_devices.TonalBuzzer`
     """
 
     def rfid_callback(card_id: str, state: RfidCardDetectState):
@@ -78,9 +78,9 @@ def register_status_led_callback(device):
 
     Compatible devices:
 
-        - :class:`components.gpio.gpioz.core.output_devices.LED`
-        - :class:`components.gpio.gpioz.core.output_devices.PWMLED`
-        - :class:`components.gpio.gpioz.core.output_devices.RGBLED`
+    * :class:`components.gpio.gpioz.core.output_devices.LED`
+    * :class:`components.gpio.gpioz.core.output_devices.PWMLED`
+    * :class:`components.gpio.gpioz.core.output_devices.RGBLED`
     """
 
     def set_status_led(state):
@@ -101,8 +101,8 @@ def register_status_buzzer_callback(device):
 
     Compatible devices:
 
-        - :class:`components.gpio.gpioz.core.output_devices.Buzzer`
-        - :class:`components.gpio.gpioz.core.output_devices.TonalBuzzer`
+    * :class:`components.gpio.gpioz.core.output_devices.Buzzer`
+    * :class:`components.gpio.gpioz.core.output_devices.TonalBuzzer`
     """
 
     def set_status_buzzer(state):
@@ -121,7 +121,7 @@ def register_status_tonalbuzzer_callback(device):
 
     Compatible devices:
 
-        - :class:`components.gpio.gpioz.core.output_devices.TonalBuzzer`
+    * :class:`components.gpio.gpioz.core.output_devices.TonalBuzzer`
     """
 
     def set_status_buzzer(state):
@@ -143,9 +143,9 @@ def register_audio_sink_change_callback(device):
 
     Compatible devices:
 
-        - :class:`components.gpio.gpioz.core.output_devices.LED`
-        - :class:`components.gpio.gpioz.core.output_devices.PWMLED`
-        - :class:`components.gpio.gpioz.core.output_devices.RGBLED`
+    * :class:`components.gpio.gpioz.core.output_devices.LED`
+    * :class:`components.gpio.gpioz.core.output_devices.PWMLED`
+    * :class:`components.gpio.gpioz.core.output_devices.RGBLED`
     """
 
     def audio_sink_change_callback(alias, sink_name, sink_index, error_state):
@@ -167,7 +167,7 @@ def register_volume_led_callback(device):
 
     Compatible devices:
 
-        - :class:`components.gpio.gpioz.core.output_devices.PWMLED`
+    * :class:`components.gpio.gpioz.core.output_devices.PWMLED`
     """
 
     def audio_volume_change_callback(volume, is_min, is_max):
@@ -191,8 +191,8 @@ def register_volume_buzzer_callback(device):
 
     Compatible devices:
 
-        - :class:`components.gpio.gpioz.core.output_devices.Buzzer`
-        - :class:`components.gpio.gpioz.core.output_devices.TonalBuzzer`
+    * :class:`components.gpio.gpioz.core.output_devices.Buzzer`
+    * :class:`components.gpio.gpioz.core.output_devices.TonalBuzzer`
     """
 
     def set_volume_buzzer(volume, is_min, is_max):
@@ -210,7 +210,7 @@ def register_volume_rgbled_callback(device):
 
     Compatible devices:
 
-        - :class:`components.gpio.gpioz.core.output_devices.RGBLED`
+    * :class:`components.gpio.gpioz.core.output_devices.RGBLED`
     """
 
     volume_to_rgb = VolumeToRGB(100, 120, 180)

diff --git a/src/jukebox/components/jingle/__init__.py b/src/jukebox/components/jingle/__init__.py
@@ -56,11 +56,12 @@ def initialize():
 def play(filename):
     """Play the jingle using the configured jingle service
 
-    Note: This runs in a separate thread. And this may cause troubles
-    when changing the volume level before
-    and after the sound playback: There is nothing to prevent another
-    thread from changing the volume and sink while playback happens
-    and afterwards we change the volume back to where it was before!
+    > [!NOTE]
+    > This runs in a separate thread. And this may cause troubles
+    > when changing the volume level before
+    > and after the sound playback: There is nothing to prevent another
+    > thread from changing the volume and sink while playback happens
+    > and afterwards we change the volume back to where it was before!
 
     There is no way around this dilemma except for not running the jingle as a
     separate thread. Currently (as thread) even the RPC is started before the sound

diff --git a/src/jukebox/components/rpc_command_alias.py b/src/jukebox/components/rpc_command_alias.py
@@ -1,7 +1,7 @@
 """
 This file provides definitions for RPC command aliases
 
-See :ref:`userguide/rpc_commands`
+See [../../builders/rpc-commands.md](RPC Commands)
 """
 
 # --------------------------------------------------------------