docs: guide: fix build with PYTHONWARNINGS=error after Sphinx update.

Author: whitequark

docs/guide.rst

@@ -170,6 +170,14 @@ Specifying a shape with a range is convenient for counters, indexes, and all oth
 
    Python ranges are *exclusive* or *half-open*, meaning they do not contain their ``.stop`` element. Because of this, values with shapes cast from a ``range(stop)`` where ``stop`` is a power of 2 are not wide enough to represent ``stop`` itself:
 
+   .. doctest::
+      :hide:
+
+      >>> import warnings
+      >>> _warning_filters_backup = warnings.catch_warnings()
+      >>> _warning_filters_backup.__enter__() # have to do this horrific hack to make it work with `PYTHONWARNINGS=error` :(
+      >>> warnings.simplefilter("default", amaranth.hdl._ast.SyntaxWarning)
+
    .. doctest::
 
       >>> fencepost = C(256, range(256))
@@ -180,6 +188,11 @@ Specifying a shape with a range is convenient for counters, indexes, and all oth
       >>> fencepost.value
       0
 
+   .. doctest::
+      :hide:
+
+      >>> _warning_filters_backup.__exit__()
+
    Amaranth detects uses of :class:`Const` and :class:`Signal` that invoke such an off-by-one error, and emits a diagnostic message.
 
 .. note::
@@ -670,6 +683,14 @@ Python expression Amaranth expression (boolean operands)
 
    When applied to Amaranth boolean values, the ``~`` operator computes negation, and when applied to Python boolean values, the ``not`` operator also computes negation. However, the ``~`` operator applied to Python boolean values produces an unexpected result:
 
+   .. doctest::
+      :hide:
+
+      >>> import warnings
+      >>> _warning_filters_backup = warnings.catch_warnings()
+      >>> _warning_filters_backup.__enter__() # have to do this horrific hack to make it work with `PYTHONWARNINGS=error` :(
+      >>> warnings.simplefilter("ignore", DeprecationWarning)
+
    .. doctest::
 
       >>> ~False
@@ -688,6 +709,11 @@ Python expression Amaranth expression (boolean operands)
       >>> ~use_stb | stb # WRONG! MSB of 2-bit wide OR expression is always 1
       (| (const 2'sd-2) (sig stb))
 
+   .. doctest::
+      :hide:
+
+      >>> _warning_filters_backup.__exit__()
+
    Amaranth automatically detects some cases of misuse of ``~`` and emits a detailed diagnostic message.
 
    .. TODO: this isn't quite reliable, #380