Improve Actors documentation

[llucax]

• Fix the outdated frequenz-channels cross-reference link
• Show inherited members in the API reference
• Use a quote admonition instead of the normal quote
• Use more readable variable names for examples
• Add a note about why we use an async context manager
• Fix numbered list indentation
• Add Lifecycle, Communication and Implementing an Actor sections
• Improve the Example section to host more than one example
• Add an example showing how to receive from multiple channels
• Add section on spawning extra tasks
• Clarify that using channels is not enforced
• Remove detailed documentation from the class (and add links to the actor module documentation)
• Add a section explaining how to initialize an actor

[llucax]

I have a couple of TODOs:

• Add an advanced section explaining how to create more tasks using the background service underneath.
• Write release notes (?) (Maybe we should only add one item saying "added a lot of docs)

[llucax]

This is based on #688.

The merge-base changed after approval.

[llucax]

Rebased on the current v0.x.x and added a few improvements:

• Add a section explaining how to initialize an actor
• Add link to the actor module documentation
• Remove detailed documentation from the class
• Remove unused (and duplicated) code annotation
• Improve wording
• Improve links consistency

They are all new commits so it should be easy to resume the reviewing 😇

[llucax]

Enabled auto-merge.

[llucax]

Mmm, there is an unrelated test failure now, I guess pylint got smarter and it is complaining about:

nox > pylint src benchmarks docs examples noxfile.py tests
************* Module src.frequenz.sdk.microgrid._data_pipeline
src/frequenz/sdk/microgrid/_data_pipeline.py:270:12: E1101: Instance of '_T' has no 'start' member (no-member)
src/frequenz/sdk/microgrid/_data_pipeline.py:296:12: E1101: Instance of '_T' has no 'start' member (no-member)
src/frequenz/sdk/microgrid/_data_pipeline.py:302:18: E1101: Instance of '_T' has no 'stop' member (no-member)
src/frequenz/sdk/microgrid/_data_pipeline.py:304:18: E1101: Instance of '_T' has no 'stop' member (no-member)
************* Module tests.microgrid.test_datapipeline
tests/microgrid/test_datapipeline.py:48:11: E1101: Instance of '_T' has no 'is_running' member (no-member)
tests/microgrid/test_datapipeline.py:52:11: E1101: Instance of '_T' has no 'is_running' member (no-member)

[shsms]

But this is already checked by mypy, pylint has an incomplete implementation that doesn't look at type hints. We see the same failure where it is checking the generated grpc code in the api client implementation as well. We should just disable the check for the whole of the sdk.

But adding some constraints in the code doesn't sound like a bad idea either:

diff --git a/src/frequenz/sdk/microgrid/_data_pipeline.py b/src/frequenz/sdk/microgrid/_data_pipeline.py
index 09f5808c..a5483e2a 100644
--- a/src/frequenz/sdk/microgrid/_data_pipeline.py
+++ b/src/frequenz/sdk/microgrid/_data_pipeline.py
@@ -30,6 +30,7 @@ _logger = logging.getLogger(__name__)
 # pylint: disable=import-outside-toplevel
 if typing.TYPE_CHECKING:
     from ..actor import (
+        Actor,
         ComponentMetricRequest,
         ComponentMetricsResamplingActor,
         DataSourcingActor,
@@ -52,7 +53,8 @@ A larger buffer size means that the DataSourcing and Resampling actors don't dro
 requests and will be able to keep up with higher request rates in larger installations.
 """
 
-_T = typing.TypeVar("_T")
+_T = typing.TypeVar("_T", bound="Actor")
 """Type variable for generic actor types."""
 
 

[llucax]

Merging without the queue because of the flakiness.