Documentation for number enhancement PR #3429 (#2049)

Co-authored-by: Maurice Makaay <mmakaay1@xs4all.net>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/number/index.rst

@@ -164,6 +164,133 @@ Configuration variables:
 - **value** (**Required**, float, :ref:`templatable <config-templatable>`):
   The value to set the number to.
 
+.. _number-increment_action:
+
+``number.increment`` Action
+***************************
+
+This is an :ref:`Action <config-action>` for incrementing a number value by its
+step size (default: 1).
+
+.. code-block:: yaml
+
+    - number.increment:
+        id: my_number
+        cycle: false
+
+    # Shorthand
+    - number.increment: my_number
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the number component to update.
+- **cycle** (**Optional**, boolean): Whether or not to set the number to its minimum
+  value when the increment pushes the value beyond its maximum value. This will only
+  work when the number component uses a minimum and maximum value.
+  Defaults to ``true``. 
+
+.. _number-decrement_action:
+
+``number.decrement`` Action
+***************************
+
+This is an :ref:`Action <config-action>` for decrementing a number value by its
+step size (default: 1).
+
+.. code-block:: yaml
+
+    - number.decrement:
+        id: my_number
+        cycle: false
+
+    # Shorthand
+    - number.decrement: my_number
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the number component to update.
+- **cycle** (**Optional**, boolean): Whether or not to set the number to its maximum
+  value when the decrement pushes the value below its minimum value. This will only
+  work when the number component uses a minimum and maximum value.
+  Defaults to ``true``. 
+
+.. _number-to-min_action:
+
+``number.to_min`` Action
+************************
+
+This is an :ref:`Action <config-action>` seting a number to its minimum value, given
+a number component that has a minimum value defined for it.
+
+.. code-block:: yaml
+
+    - number.to_min:
+        id: my_number
+
+    # Shorthand
+    - number.to_min: my_number
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the number component to update.
+
+.. _number-to-max_action:
+
+``number.to_max`` Action
+************************
+
+This is an :ref:`Action <config-action>` seting a number to its maximum value (given
+a number component that has a maximum value defined for it.
+
+.. code-block:: yaml
+
+    - number.to_max:
+        id: my_number
+
+    # Shorthand
+    - number.to_max: my_number
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the number component to update.
+
+.. _number-operation_action:
+
+``number.operation`` Action
+***************************
+
+This is an :ref:`Action <config-action>` that can be used to perform an operation
+on a number component (set to minimum or maximum value, decrement, increment),
+using a generic templatable action call.
+
+.. code-block:: yaml
+
+    # Using values
+    - number.operation:
+        id: my_number
+        operation: Increment
+        cycle: true
+
+    # Or templated (lambda)
+    - number.operation:
+        id: my_number
+        operation: !lambda "return NUMBER_OP_INCREMENT;"
+        cycle: !lambda: "return true;"
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the number to update.
+- **operation** (**Required**, string, :ref:`templatable <config-templatable>`):
+  What operation to perform on the number component. One of ``TO_MIN``,
+  ``TO_MAX``, ``DECREMENT`` or ``INCREMENT`` (case insensitive). When writing a
+  lambda for this field, then return one of the following enum values:
+  ``NUMBER_OP_TO_MIN``, ``NUMBER_OP_TO_MAX``, ``NUMBER_OP_DECREMENT`` or
+  ``NUMBER_OP_INCREMENT``.
+- **cycle** (**Optional**, bool, :ref:`templatable <config-templatable>`):
+  Can be used with ``DECREMENT`` or ``INCREMENT`` to specify whether or not to
+  wrap around the value when respectively the minimum or maximum value of the
+  number is exceeded.
+
 .. _number-lambda_calls:
 
 lambda calls
@@ -172,7 +299,7 @@ lambda calls
 From :ref:`lambdas <config-lambda>`, you can call several methods on all numbers to do some
 advanced stuff (see the full API Reference for more info).
 
-- ``make_call()``: Set the number value.
+- ``.make_call()``: Make a call for updating the number value.
 
   .. code-block:: cpp
 
@@ -181,6 +308,11 @@ advanced stuff (see the full API Reference for more info).
       call.set_value(42);
       call.perform();
 
+  Check the API reference for information on the methods that are available for
+  the ``NumberCall`` object. You can for example also use ``call.to_min()``
+  to set the number to its minimum value or ``call.increment(true)`` to increment
+  the number by its step size with the cycle feature enabled.
+
 - ``.state``: Retrieve the current value of the number. Is ``NAN`` if no value has been read or set.
 
   .. code-block:: cpp
@@ -191,7 +323,8 @@ advanced stuff (see the full API Reference for more info).
 See Also
 --------
 
-- :apiref:`number/number.h`
+- :apiref:`Number <number/number.h>`
+- :apiref:`NumberCall <number/number_call.h>`
 - :ghedit:`Edit`
 
 .. toctree::

guides/automations.rst

@@ -389,7 +389,7 @@ All Actions
 - :ref:`ds1307.read_time <ds1307-read_time_action>` / :ref:`ds1307.write_time <ds1307-write_time_action>`
 - :ref:`cs5460a.restart <cs5460a-restart_action>`
 - :ref:`pzemac.reset_energy <pzemac-reset_energy_action>`
-- :ref:`number.set <number-set_action>`
+- :ref:`number.set <number-set_action>` / :ref:`number.to_min <number-to-min_action>` / :ref:`number.to_max <number-to-max_action>` / :ref:`number.decrement <number-decrement_action>` / :ref:`number.increment <number-increment_action>` / :ref:`number.operation <number-operation_action>`
 - :ref:`select.set <select-set_action>` / :ref:`select.set_index <select-set_index_action>` / :ref:`select.first <select-first_action>` / :ref:`select.last <select-last_action>` / :ref:`select.previous <select-previous_action>`  / :ref:`select.next <select-next_action>`  / :ref:`select.operation <select-operation_action>` 
 
 .. _config-condition: