Improve Actors documentation (#689)

- 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

Author: llucax

.github/workflows/ci.yaml

@@ -301,7 +301,7 @@ jobs:
 
   publish-docs:
     name: Publish documentation website to GitHub pages
-    needs: ["nox", "nox-cross-arch-all", "test-installation"]
+    needs: ["nox-all", "nox-cross-arch-all", "test-installation"]
     if: github.event_name == 'push'
     runs-on: ubuntu-20.04
     permissions:

RELEASE_NOTES.md

@@ -10,7 +10,17 @@
 
 ## New Features
 
-- A tutorial section and a getting started tutorial
+- New and improved documentation.
+
+  * A new *Introduction* section was added, with:
+
+    + A glossary.
+    + An introduction to actors.
+
+  * A new *Tutorials* section was added, with:
+
+    + A getting started tutorial.
+
 - In `OrderedRingBuffer`:
   - Rename `datetime_to_index` to `to_internal_index` to avoid confusion between the internal index and the external index.
   - Remove `__setitem__` method to enforce usage of dedicated `update` method only.

mkdocs.yml

@@ -98,6 +98,7 @@ plugins:
           options:
             paths: ["src"]
             docstring_section_style: spacy
+            inherited_members: true
             merge_init_into_class: false
             show_category_heading: true
             show_root_heading: true
@@ -107,7 +108,7 @@ plugins:
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv
             - https://frequenz-floss.github.io/frequenz-api-common/v0.3/objects.inv
-            - https://frequenz-floss.github.io/frequenz-channels-python/v0.14/objects.inv
+            - https://frequenz-floss.github.io/frequenz-channels-python/v0.16/objects.inv
             - https://frequenz-floss.github.io/frequenz-api-microgrid/v0.15/objects.inv
             - https://grpc.github.io/grpc/python/objects.inv
             - https://networkx.org/documentation/stable/objects.inv