From b92eb447b4c6be51d3805baa4b727593a9351ba2 Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Sat, 8 Jun 2019 11:57:12 +0200
Subject: [PATCH] doc: add extra units

---
 doc/common/signaltypes.rst | 49 +++++++++++++++++++++++++++++++-------
 pybricks/_common.py        | 14 +++++------
 2 files changed, 47 insertions(+), 16 deletions(-)

diff --git a/doc/common/signaltypes.rst b/doc/common/signaltypes.rst
index 9789cad..a7636b6 100644
--- a/doc/common/signaltypes.rst
+++ b/doc/common/signaltypes.rst
@@ -107,27 +107,58 @@ For example, the speed of a robotic vehicle is expressed in mm/s.
 
 .. _acceleration:
 
-rotational acceleration: deg/s/s -------------------------------- Rotational
-acceleration, or *angular acceleration* describes how fast the rotational speed
-changes. This is expressed as the change of the number of degrees per second,
-during one second (deg/s/s). This is also commonly written as  :math:`deg/s^2`.
+rotational acceleration: deg/s/s
+--------------------------------
+
+Rotational acceleration, or *angular acceleration* describes how fast the
+rotational speed changes. This is expressed as the change of the number of
+degrees per second, during one second (deg/s/s). This is also commonly written
+as  :math:`deg/s^2`.
 
 For example, you can adjust the rotational acceleration setting of a
 :meth:`Motor <.ev3devices.Motor.set_run_settings>` to change how smoothly or
 how quickly it reaches the constant speed set point.
 
+.. _force:
+
+force: N
+------------
+Force values are expressed in newtons (N).
+
+While we recommend working with newtons in your programs, you can use the
+following table to convert to and from other units.
+
++---------+------+-------+-----------------------------+
+|         | mN   | N     | lbf                         |
++---------+------+-------+-----------------------------+
+| 1 mN =  | 1    | 0.001 | :math:`2.248 \cdot 10^{-4}` |
++---------+------+-------+-----------------------------+
+| 1 N =   | 1000 | 1     | 0.2248                      |
++---------+------+-------+-----------------------------+
+| 1 lbf = | 4448 | 4.448 | 1                           |
++---------+------+-------+-----------------------------+
 
 .. _percentage:
 
 percentage: %
 --------------
 
-Some signals do not have specific units but range from a minimum (0%) to a
-maximum (100%). A specific type of percentages are :ref:`relative distances
-<relativedistance>`.
+Some signals do not have specific units. They range from a minimum (0%) to a
+maximum (100%). Specifics type of percentages are :ref:`relative distances
+<relativedistance>` or  :ref:`brightnesses <brightness>`.
 
-For example, the sound :meth:`volume <.ev3brick.sound.beep>` ranges from 0% to
-100%.
+Another example is the sound :meth:`volume <.ev3brick.sound.beep>`, which
+ranges from 0% (silent) to 100% (loudest).
+
+.. _brightness:
+
+brightness: %
+--------------
+
+The perceived brightness of a light is expressed as a percentage. It is 0% when
+the light is off and 100% when the light is fully on. When you choose 50%, this
+means that the light is perceived as approximately half as bright to the human
+eye.
 
 .. _frequency:
 
diff --git a/pybricks/_common.py b/pybricks/_common.py
index ab97809..30f24d8 100644
--- a/pybricks/_common.py
+++ b/pybricks/_common.py
@@ -427,7 +427,7 @@ class Light():
         """Turn on the light at the specified brightness.
 
         Arguments:
-            brightness (:ref:`percentage`):
+            brightness (:ref:`brightness`):
                 Brightness of the light (*Default*: 100).
         """
 
@@ -445,7 +445,7 @@ class ColorLight():
         Arguments:
             color (Color): Color of the light. The light turns off if you
                            choose ``None`` or a color that is not available.
-            brightness (:ref:`percentage`): Brightness of the selected
+            brightness (:ref:`brightness`): Brightness of the selected
                                             color (*Default*: 100).
         """
         pass
@@ -458,9 +458,9 @@ class ColorLight():
         """Set the brightness of the red, green, and blue light.
 
         Arguments:
-            red (:ref:`percentage`): Brightness of the red light.
-            green (:ref:`percentage`): Brightness of the green light.
-            blue (:ref:`percentage`): Brightness of the blue light.
+            red (:ref:`brightness`): Brightness of the red light.
+            green (:ref:`brightness`): Brightness of the green light.
+            blue (:ref:`brightness`): Brightness of the blue light.
         """
         pass
 
@@ -509,7 +509,7 @@ class LightGrid():
         """Show an image made up of pixels of a given brightness.
 
         Arguments:
-            matrix (2D Array): Matrix of intensities (:ref:`percentage`).
+            matrix (2D Array): Matrix of intensities (:ref:`brightness`).
             clear (bool): Whether to turn off all the lights before showing
                 the new image (*Default*: ``True``). If you choose ``False``,
                 the given matrix is added to one already shown.
@@ -522,7 +522,7 @@ class LightGrid():
         Arguments:
             x (int): horizontal index, starting at 0 from the left.
             y (int): vertical index, starting at 0 from the top.
-            brightness (:ref:`percentage`): Brightness of the pixel.
+            brightness (:ref:`brightness`): Brightness of the pixel.
         """
         pass