Document methods for creating data pipeline interface objects (#739)

Also clarify in `client` package that it is a low-level one.

Author: shsms

src/frequenz/sdk/microgrid/client/__init__.py

@@ -3,7 +3,7 @@
 
 """Microgrid API client.
 
-This package provides an easy way to connect to the microgrid API.
+This package provides a low-level interface for interacting with the microgrid API.
 """
 
 from ._client import MicrogridApiClient, MicrogridGrpcClient

src/frequenz/sdk/timeseries/battery_pool/_battery_pool.py

@@ -39,8 +39,10 @@
 class BatteryPool:
     """An interface for interaction with pools of batteries.
 
-    Use the [microgrid.battery_pool][frequenz.sdk.microgrid.battery_pool] method for
-    creating `BatteryPool` instances.
+    !!! note
+        `BatteryPool` instances are not meant to be created directly by users.  Use the
+        [`microgrid.battery_pool`][frequenz.sdk.microgrid.battery_pool] method for
+        creating `BatteryPool` instances.
 
     Provides:
       - properties for fetching reporting streams of instantaneous
@@ -63,6 +65,11 @@ def __init__(
     ):
         """Create a BatteryPool instance.
 
+        !!! note
+            `BatteryPool` instances are not meant to be created directly by users.  Use
+            the [`microgrid.battery_pool`][frequenz.sdk.microgrid.battery_pool] method
+            for creating `BatteryPool` instances.
+
         Args:
             battery_pool_ref: The battery pool reference store instance.
             name: An optional name used to identify this instance of the pool or a

src/frequenz/sdk/timeseries/ev_charger_pool/_ev_charger_pool.py

@@ -53,7 +53,26 @@ class EVChargerData:
 
 
 class EVChargerPool:
-    """Interactions with EV Chargers."""
+    """An interface for interaction with pools of EV Chargers.
+
+    !!! note
+        `EVChargerPool` instances are not meant to be created directly by users. Use the
+        [`microgrid.ev_charger_pool`][frequenz.sdk.microgrid.ev_charger_pool] method for
+        creating `EVChargerPool` instances.
+
+    Provides:
+      - Aggregate [`power`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.power]
+        and 3-phase
+        [`current`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.current]
+        measurements of the EV Chargers in the pool.
+      - The
+        [`component_data`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.component_data]
+        method for fetching the 3-phase current and state of individual EV Chargers in
+        the pool.
+      - The
+        [`set_bounds`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.set_bounds]
+        method for limiting the max current of individual EV Chargers in the pool.
+    """
 
     def __init__(
         self,
@@ -64,6 +83,11 @@ def __init__(
     ) -> None:
         """Create an `EVChargerPool` instance.
 
+        !!! note
+            `EVChargerPool` instances are not meant to be created directly by users. Use
+            the [`microgrid.ev_charger_pool`][frequenz.sdk.microgrid.ev_charger_pool]
+            method for creating `EVChargerPool` instances.
+
         Args:
             channel_registry: A channel registry instance shared with the resampling
                 actor.

src/frequenz/sdk/timeseries/logical_meter/_logical_meter.py

@@ -32,6 +32,11 @@ class LogicalMeter:
     microgrid.  These methods return `FormulaReceiver` objects, which can be used like
     normal `Receiver`s, but can also be composed to form higher-order formula streams.
 
+    !!! note
+        `LogicalMeter` instances are not meant to be created directly by users.  Use the
+        [`microgrid.logical_meter`][frequenz.sdk.microgrid.logical_meter] method for
+        creating `LogicalMeter` instances.
+
     Example:
         ```python
         from datetime import timedelta
@@ -71,7 +76,12 @@ def __init__(
         channel_registry: ChannelRegistry,
         resampler_subscription_sender: Sender[ComponentMetricRequest],
     ) -> None:
-        """Create a `LogicalMeter instance`.
+        """Create a `LogicalMeter` instance.
+
+        !!! note
+            `LogicalMeter` instances are not meant to be created directly by users.  Use
+            the [`microgrid.logical_meter`][frequenz.sdk.microgrid.logical_meter] method
+            for creating `LogicalMeter` instances.
 
         Args:
             channel_registry: A channel registry instance shared with the resampling