Remove detailed documentation from the class

The detailed documentation for how to use and implement actors now lives
in the module. The class documentation is removed because it is not
comprehensive enough and to avoid duplication.

A link to the module documentation will be added in a separate commit.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

src/frequenz/sdk/actor/_actor.py

@@ -15,125 +15,10 @@
 class Actor(BackgroundService, abc.ABC):
     """A primitive unit of computation that runs autonomously.
 
-    From [Wikipedia](https://en.wikipedia.org/wiki/Actor_model), an actor is:
-
-    > [...] the basic building block of concurrent computation. In response to
-    > a message it receives, an actor can: make local decisions, create more actors,
-    > send more messages, and determine how to respond to the next message received.
-    > Actors may modify their own private state, but can only affect each other
-    > indirectly through messaging (removing the need for lock-based synchronization).
-
-    [Channels](https://github.com/frequenz-floss/frequenz-channels-python/) can be used
-    to implement communication between actors, as shown in the examples below.
-
     To implement an actor, subclasses must implement the `_run()` method, which should
     run the actor's logic. The `_run()` method is called by the base class when the
     actor is started, and is expected to run until the actor is stopped.
 
-    If an unhandled exception is raised in the `_run()` method, the actor will be
-    restarted automatically. Unhandled [`BaseException`][]s will cause the actor to stop
-    immediately and will be re-raised.
-
-    !!! warning
-
-        As actors manage [`asyncio.Task`][] objects, a reference to them must be held
-        for as long as the actor is expected to be running, otherwise its tasks will be
-        cancelled and the actor will stop. For more information, please refer to the
-        [Python `asyncio`
-        documentation](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task).
-
-    Example: Example of an actor receiving from two receivers
-
-        ```python
-        from frequenz.channels import Broadcast, Receiver, Sender
-        from frequenz.channels.util import select, selected_from
-
-        class EchoActor(Actor):
-            def __init__(
-                self,
-                recv1: Receiver[bool],
-                recv2: Receiver[bool],
-                output: Sender[bool],
-            ) -> None:
-                super().__init__()
-                self._recv1 = recv1
-                self._recv2 = recv2
-                self._output = output
-
-            async def _run(self) -> None:
-                async for selected in select(self._recv1, self._recv2):
-                    if selected_from(selected, self._recv1):
-                        await self._output.send(selected.value)
-                    elif selected_from(selected, self._recv1):
-                        await self._output.send(selected.value)
-                    else:
-                        assert False, "Unknown selected channel"
-
-
-        input_channel_1 = Broadcast[bool]("input_channel_1")
-        input_channel_2 = Broadcast[bool]("input_channel_2")
-        input_channel_2_sender = input_channel_2.new_sender()
-
-        echo_channel = Broadcast[bool]("EchoChannel")
-        echo_receiver = echo_channel.new_receiver()
-
-        async with EchoActor(
-            input_channel_1.new_receiver(),
-            input_channel_2.new_receiver(),
-            echo_channel.new_sender(),
-        ):
-            await input_channel_2_sender.send(True)
-            print(await echo_receiver.receive())
-        ```
-
-    Example: Example of composing two actors
-
-        ```python
-        from frequenz.channels import Broadcast, Receiver, Sender
-
-        class Actor1(Actor):
-            def __init__(
-                self,
-                recv: Receiver[bool],
-                output: Sender[bool],
-            ) -> None:
-                super().__init__()
-                self._recv = recv
-                self._output = output
-
-            async def _run(self) -> None:
-                async for msg in self._recv:
-                    await self._output.send(msg)
-
-
-        class Actor2(Actor):
-            def __init__(
-                self,
-                recv: Receiver[bool],
-                output: Sender[bool],
-            ) -> None:
-                super().__init__()
-                self._recv = recv
-                self._output = output
-
-            async def _run(self) -> None:
-                async for msg in self._recv:
-                    await self._output.send(msg)
-
-        input_channel: Broadcast[bool] = Broadcast("Input to Actor1")
-        middle_channel: Broadcast[bool] = Broadcast("Actor1 -> Actor2 stream")
-        output_channel: Broadcast[bool] = Broadcast("Actor2 output")
-
-        input_sender = input_channel.new_sender()
-        output_receiver = output_channel.new_receiver()
-
-        async with (
-            Actor1(input_channel.new_receiver(), middle_channel.new_sender()),
-            Actor2(middle_channel.new_receiver(), output_channel.new_sender()),
-        ):
-            await input_sender.send(True)
-            print(await output_receiver.receive())
-        ```
     """
 
     _restart_limit: int | None = None