Skip to contentSkip to conversation

Documentation: leds: improve readibility of multicolor doc

PATCH Applied Jean-Michel Hautbois 3 participants 5 messages Apr 21, 2025 – May 6, 2025

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Documentation: leds: improve readibility of multicolor doc

When reading the documentation of multicolor leds, the HTML output is not easy to read. Improve it by adding a few markups, splitting the console in a dedicated block.

---
 Documentation/leds/leds-class-multicolor.rst | 82 +++++++++++++++++-----------
 1 file changed, 51 insertions(+), 31 deletions(-)
Documentation/leds/leds-class-multicolor.rst +51 -31
index c57b98bfd38715b705c555efeb8e5f9076b1b787..c6b47b4093c47360b238b49d3cbfa055a9b484e5 100644
@@ -18,24 +18,28 @@ array.  These files are children under the LED parent node created by the
 led_class framework.  The led_class framework is documented in led-class.rst
 within this documentation directory.
 
-Each colored LED will be indexed under the multi_* files. The order of the
-colors will be arbitrary. The multi_index file can be read to determine the
+Each colored LED will be indexed under the ``multi_*`` files. The order of the
+colors will be arbitrary. The ``multi_index`` file can be read to determine the
 color name to indexed value.
 
-The multi_index file is an array that contains the string list of the colors as
-they are defined in each multi_* array file.
+The ``multi_index`` file is an array that contains the string list of the colors as
+they are defined in each ``multi_*`` array file.
 
-The multi_intensity is an array that can be read or written to for the
+The ``multi_intensity`` is an array that can be read or written to for the
 individual color intensities.  All elements within this array must be written in
 order for the color LED intensities to be updated.
 
 Directory Layout Example
 ========================
-root:/sys/class/leds/multicolor:status# ls -lR
--rw-r--r--    1 root     root          4096 Oct 19 16:16 brightness
--r--r--r--    1 root     root          4096 Oct 19 16:16 max_brightness
--r--r--r--    1 root     root          4096 Oct 19 16:16 multi_index
--rw-r--r--    1 root     root          4096 Oct 19 16:16 multi_intensity
+.. code-block:: console
+
+    root:/sys/class/leds/multicolor:status# ls -lR
+    -rw-r--r--    1 root     root          4096 Oct 19 16:16 brightness
+    -r--r--r--    1 root     root          4096 Oct 19 16:16 max_brightness
+    -r--r--r--    1 root     root          4096 Oct 19 16:16 multi_index
+    -rw-r--r--    1 root     root          4096 Oct 19 16:16 multi_intensity
+
+..
 
 Multicolor Class Brightness Control
 ===================================
@@ -43,27 +47,31 @@ The brightness level for each LED is calculated based on the color LED
 intensity setting divided by the global max_brightness setting multiplied by
 the requested brightness.
 
-led_brightness = brightness * multi_intensity/max_brightness
+``led_brightness = brightness * multi_intensity/max_brightness``
 
 Example:
 A user first writes the multi_intensity file with the brightness levels
 for each LED that are necessary to achieve a certain color output from a
 multicolor LED group.
 
-cat /sys/class/leds/multicolor:status/multi_index
-green blue red
+.. code-block:: console
+
+    # cat /sys/class/leds/multicolor:status/multi_index
+    green blue red
 
-echo 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity
+    # echo 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity
 
-red -
-	intensity = 138
-	max_brightness = 255
-green -
-	intensity = 43
-	max_brightness = 255
-blue -
-	intensity = 226
-	max_brightness = 255
+    red -
+    	intensity = 138
+    	max_brightness = 255
+    green -
+    	intensity = 43
+    	max_brightness = 255
+    blue -
+    	intensity = 226
+    	max_brightness = 255
+
+..
 
 The user can control the brightness of that multicolor LED group by writing the
 global 'brightness' control.  Assuming a max_brightness of 255 the user
@@ -71,16 +79,28 @@ may want to dim the LED color group to half.  The user would write a value of
 128 to the global brightness file then the values written to each LED will be
 adjusted base on this value.
 
-cat /sys/class/leds/multicolor:status/max_brightness
-255
-echo 128 > /sys/class/leds/multicolor:status/brightness
+.. code-block:: console
+
+    # cat /sys/class/leds/multicolor:status/max_brightness
+    255
+    # echo 128 > /sys/class/leds/multicolor:status/brightness
 
-adjusted_red_value = 128 * 138/255 = 69
-adjusted_green_value = 128 * 43/255 = 21
-adjusted_blue_value = 128 * 226/255 = 113
+..
+
+.. code-block:: none
+
+    adjusted_red_value = 128 * 138/255 = 69
+    adjusted_green_value = 128 * 43/255 = 21
+    adjusted_blue_value = 128 * 226/255 = 113
+
+..
 
 Reading the global brightness file will return the current brightness value of
 the color LED group.
 
-cat /sys/class/leds/multicolor:status/brightness
-128
+.. code-block:: console
+
+    # cat /sys/class/leds/multicolor:status/brightness
+    128
+
+..

---
base-commit: 9d7a0577c9db35c4cc52db90bc415ea248446472
change-id: 20250421-leds-doc-dd85db13fda4

Best regards,

Signature · 1 line
Jean-Michel Hautbois <[email protected]>
#1 lore raw

Documentation/leds/leds-class-multicolor.rst array. These files are children under the LED parent node created by the · line 36

Quoted 3 lines · Jean-Michel Hautbois

+.. code-block:: console

Documentation/leds/leds-class-multicolor.rst +2 -0
+
+    root:/sys/class/leds/multicolor:status# ls -lR

The equivalent is ``ls -lR /sys/class/leds/multicolor``.

Quoted 24 lines
Documentation/leds/leds-class-multicolor.rst +6 -0
+    -rw-r--r--    1 root     root          4096 Oct 19 16:16 brightness
+    -r--r--r--    1 root     root          4096 Oct 19 16:16 max_brightness
+    -r--r--r--    1 root     root          4096 Oct 19 16:16 multi_index
+    -rw-r--r--    1 root     root          4096 Oct 19 16:16 multi_intensity
+
+..

<snipped>...

Documentation/leds/leds-class-multicolor.rst +5 -5
@@ -71,16 +79,28 @@ may want to dim the LED color group to half.  The user would write a value of
 128 to the global brightness file then the values written to each LED will be
 adjusted base on this value.
 
-cat /sys/class/leds/multicolor:status/max_brightness
-255
-echo 128 > /sys/class/leds/multicolor:status/brightness
+.. code-block:: console
+
+    # cat /sys/class/leds/multicolor:status/max_brightness
+    255
+    # echo 128 > /sys/class/leds/multicolor:status/brightness
 
-adjusted_red_value = 128 * 138/255 = 69
-adjusted_green_value = 128 * 43/255 = 21

Documentation/leds/leds-class-multicolor.rst may want to dim the LED color group to half. The user would write a value of · line 96

Quoted 10 lines
Documentation/leds/leds-class-multicolor.rst +9 -1
-adjusted_blue_value = 128 * 226/255 = 113
+..
+
+.. code-block:: none
+
+    adjusted_red_value = 128 * 138/255 = 69
+    adjusted_green_value = 128 * 43/255 = 21
+    adjusted_blue_value = 128 * 226/255 = 113
+
+..

Are these adjusted values intended to be part of previous block on brightness status? If not, I'd like to interleave these two blocks with "The adjusted values are now::".

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw

Hi Bagas,

Quoted 7 lines · Bagas Sanjaya

Documentation/leds/leds-class-multicolor.rst array. These files are children under the LED parent node created by the · line 36

Quoted 3 lines · Jean-Michel Hautbois

+.. code-block:: console

Documentation/leds/leds-class-multicolor.rst +2 -0
+
+    root:/sys/class/leds/multicolor:status# ls -lR

The equivalent is ``ls -lR /sys/class/leds/multicolor``.

This patch was only to add markups, I did not want to change the content more than that. The result of ls -lR must also be in the same code-block, so I am not certain your proposal is equivalent ?

Quoted 22 lines
Quoted 22 lines
Documentation/leds/leds-class-multicolor.rst +6 -0
+    -rw-r--r--    1 root     root          4096 Oct 19 16:16 brightness
+    -r--r--r--    1 root     root          4096 Oct 19 16:16 max_brightness
+    -r--r--r--    1 root     root          4096 Oct 19 16:16 multi_index
+    -rw-r--r--    1 root     root          4096 Oct 19 16:16 multi_intensity
+
+..

<snipped>...

Documentation/leds/leds-class-multicolor.rst +5 -3
@@ -71,16 +79,28 @@ may want to dim the LED color group to half.  The user would write a value of
  128 to the global brightness file then the values written to each LED will be
  adjusted base on this value.
 
-cat /sys/class/leds/multicolor:status/max_brightness
-255
-echo 128 > /sys/class/leds/multicolor:status/brightness
+.. code-block:: console
+
+    # cat /sys/class/leds/multicolor:status/max_brightness
+    255
+    # echo 128 > /sys/class/leds/multicolor:status/brightness
 
Quoted 16 lines

Documentation/leds/leds-class-multicolor.rst may want to dim the LED color group to half. The user would write a value of · line 96

Quoted 12 lines
Documentation/leds/leds-class-multicolor.rst +9 -3
-adjusted_red_value = 128 * 138/255 = 69
-adjusted_green_value = 128 * 43/255 = 21
-adjusted_blue_value = 128 * 226/255 = 113
+..
+
+.. code-block:: none
+
+    adjusted_red_value = 128 * 138/255 = 69
+    adjusted_green_value = 128 * 43/255 = 21
+    adjusted_blue_value = 128 * 226/255 = 113
+
+..

Are these adjusted values intended to be part of previous block on brightness status? If not, I'd like to interleave these two blocks with "The adjusted values are now::".

Interesting, yes, it could be added.

Thanks !
JM

#3 lore raw
Quoted 8 lines · Jean-Michel Hautbois

Hi Bagas,

Quoted 5 lines · Bagas Sanjaya
Quoted 3 lines · Jean-Michel Hautbois

+.. code-block:: console

Documentation/leds/leds-class-multicolor.rst +2 -0
+
+    root:/sys/class/leds/multicolor:status# ls -lR
Quoted 6 lines
Quoted 2 lines

The equivalent is ``ls -lR /sys/class/leds/multicolor``.

This patch was only to add markups, I did not want to change the content more than that. The result of ls -lR must also be in the same code-block, so I am not certain your proposal is equivalent ?

I mean the output is same. But, I agree with your approach to only add markup.

Quoted 37 lines
Quoted 28 lines
Quoted 28 lines
Documentation/leds/leds-class-multicolor.rst +6 -0
+    -rw-r--r--    1 root     root          4096 Oct 19 16:16 brightness
+    -r--r--r--    1 root     root          4096 Oct 19 16:16 max_brightness
+    -r--r--r--    1 root     root          4096 Oct 19 16:16 multi_index
+    -rw-r--r--    1 root     root          4096 Oct 19 16:16 multi_intensity
+
+..

<snipped>...

Documentation/leds/leds-class-multicolor.rst +10 -6
@@ -71,16 +79,28 @@ may want to dim the LED color group to half.  The user would write a value of
  128 to the global brightness file then the values written to each LED will be
  adjusted base on this value.
-cat /sys/class/leds/multicolor:status/max_brightness
-255
-echo 128 > /sys/class/leds/multicolor:status/brightness
+.. code-block:: console
+
+    # cat /sys/class/leds/multicolor:status/max_brightness
+    255
+    # echo 128 > /sys/class/leds/multicolor:status/brightness
-adjusted_red_value = 128 * 138/255 = 69
-adjusted_green_value = 128 * 43/255 = 21
-adjusted_blue_value = 128 * 226/255 = 113
+..
+
+.. code-block:: none
+
+    adjusted_red_value = 128 * 138/255 = 69
Quoted 8 lines

Documentation/leds/leds-class-multicolor.rst may want to dim the LED color group to half. The user would write a value of · line 96

Quoted 4 lines
Documentation/leds/leds-class-multicolor.rst +4 -0
+    adjusted_green_value = 128 * 43/255 = 21
+    adjusted_blue_value = 128 * 226/255 = 113
+
+..

Are these adjusted values intended to be part of previous block on brightness status? If not, I'd like to interleave these two blocks with "The adjusted values are now::".

Quoted 1 line

Interesting, yes, it could be added.

OK, thanks!

Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer Applied
#4 lore raw
In reply to Jean-Michel Hautbois
Quoted 8 lines · Jean-Michel Hautbois

When reading the documentation of multicolor leds, the HTML output is not easy to read. Improve it by adding a few markups, splitting the console in a dedicated block.

---
 Documentation/leds/leds-class-multicolor.rst | 82 +++++++++++++++++-----------
 1 file changed, 51 insertions(+), 31 deletions(-)

Applied, thanks.

jon