Remove boilerplate from examples in the user guide (#276)

We filter out all the boilerplate (importing, declaring some variables)
from the code shown in the user guide, as it is distracting for such a
high-level introduction. This means more examples listed in modules have
the boilerplate removed from the generated docs. We do this by adding
the [pymdownx-superfence-filter-lines] markdown extension.

Examples in classes or functions, that usually show up in the API docs
are kept as before, with all the code. This is so users wanting to dive
deeper into the library can still copy&paste code snippets from these
examples and expect them to mostly work.

[pymdownx-superfence-filter-lines]:
https://github.com/frequenz-floss/pymdownx-superfence-filter-lines-python

Author: llucax

mkdocs.yml

@@ -83,6 +83,10 @@ markdown_extensions:
         - name: mermaid
           class: mermaid
           format: !!python/name:pymdownx.superfences.fence_code_format
+        - name: "*"
+          class: "highlight"
+          format: !!python/name:pymdownx_superfence_filter_lines.do_format
+          validator: !!python/name:pymdownx_superfence_filter_lines.do_validate
   - pymdownx.tabbed
   - pymdownx.tasklist:
       custom_checkbox: true

pyproject.toml

@@ -56,6 +56,7 @@ dev-mkdocs = [
   "mkdocs-macros-plugin == 1.0.5",
   "mkdocs-material == 9.5.6",
   "mkdocstrings[python] == 0.24.0",
+  "pymdownx-superfence-filter-lines == 0.1.0",
 ]
 dev-mypy = [
   # For checking the noxfile, docs/ script, and tests

src/frequenz/channels/_exceptions.py

@@ -19,7 +19,7 @@
 was closed while seding or receiving a message, the original exception will be
 available as the cause of the exception:
 
-```python
+```python show_lines="6:"
 from frequenz.channels import Anycast, ChannelClosedError, SenderError
 
 channel = Anycast[int](name="test-channel")
@@ -44,7 +44,7 @@
     explicitly calling [`receive()`][frequenz.channels.Receiver.receive] on the
     receiver after the iteration is done:
 
-    ```python
+    ```python show_lines="6:"
     from frequenz.channels import Anycast, ChannelClosedError, ReceiverStoppedError
 
     channel = Anycast[int](name="test-channel")

src/frequenz/channels/_merge.py

@@ -9,7 +9,7 @@
 stream, you can use [`merge()`][frequenz.channels.merge] to create a new receiver that
 will receive messages from all the given receivers:
 
-```python
+```python show_lines="8:"
 from frequenz.channels import Anycast, Receiver, merge
 
 channel1: Anycast[int] = Anycast(name="channel1")

src/frequenz/channels/_receiver.py

@@ -11,7 +11,7 @@
 iterators][typing.AsyncIterator], so the easiest way to receive values from them as
 a stream is to use `async for`:
 
-```python
+```python show_lines="6:"
 from frequenz.channels import Anycast
 
 channel = Anycast[int](name="test-channel")
@@ -24,7 +24,7 @@
 If you need to receive values in different places or expecting a particular
 sequence, you can use the [`receive()`][frequenz.channels.Receiver.receive] method:
 
-```python
+```python show_lines="6:"
 from frequenz.channels import Anycast
 
 channel = Anycast[int](name="test-channel")
@@ -42,7 +42,7 @@
 If you need to transform the received values, receivers provide a
 [`map()`][frequenz.channels.Receiver.map] method to easily do so:
 
-```python
+```python show_lines="6:"
 from frequenz.channels import Anycast
 
 channel = Anycast[int](name="test-channel")
@@ -71,7 +71,7 @@
 closed), a [`ReceiverStoppedError`][frequenz.channels.ReceiverStoppedError] exception
 is raised by [`receive()`][frequenz.channels.Receiver.receive] method.
 
-```python
+```python show_lines="6:"
 from frequenz.channels import Anycast
 
 channel = Anycast[int](name="test-channel")
@@ -88,7 +88,7 @@
 When used as an async iterator, the iteration will just stop without raising an
 exception:
 
-```python
+```python show_lines="6:"
 from frequenz.channels import Anycast
 
 channel = Anycast[int](name="test-channel")

src/frequenz/channels/_select.py

@@ -18,7 +18,7 @@
 function to check the source of the message, and the
 [`value`][frequenz.channels.Selected.value] attribute to access the message:
 
-```python
+```python show_lines="8:"
 from frequenz.channels import Anycast, ReceiverStoppedError, select, selected_from
 
 channel1: Anycast[int] = Anycast(name="channel1")
@@ -51,7 +51,7 @@
     If for some reason you want to ignore a received value, just add the receiver to
     the if-chain and do nothing with the value:
 
-    ```python
+    ```python show_lines="8:"
     from frequenz.channels import Anycast, select, selected_from
 
     channel1: Anycast[int] = Anycast(name="channel1")
@@ -76,7 +76,7 @@
 [`was_stopped()`][frequenz.channels.Selected.was_stopped] method to check if the
 selected [receiver][frequenz.channels.Receiver] was stopped:
 
-```python
+```python show_lines="8:"
 from frequenz.channels import Anycast, select, selected_from
 
 channel1: Anycast[int] = Anycast(name="channel1")
@@ -111,7 +111,7 @@
 
 You can use a try-except block to handle exceptions as usual:
 
-```python
+```python show_lines="8:"
 from frequenz.channels import Anycast, ReceiverStoppedError, select, selected_from
 
 channel1: Anycast[int] = Anycast(name="channel1")

src/frequenz/channels/_sender.py

@@ -10,7 +10,7 @@
 usually created by calling `channel.new_sender()`, and are a very simple abstraction
 that only provides a single [`send()`][frequenz.channels.Sender.send] method:
 
-```python
+```python show_lines="6:"
 from frequenz.channels import Anycast
 
 channel = Anycast[int](name="test-channel")
@@ -36,7 +36,7 @@
 If there is any failure sending a message,
 a [SenderError][frequenz.channels.SenderError] exception is raised.
 
-```python
+```python show_lines="6:"
 from frequenz.channels import Anycast
 
 channel = Anycast[int](name="test-channel")