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

Backported from 556faea

Author: Jean THOMAS

README.md

@@ -1,4 +1,4 @@
-# Amaranth HDL (previously nMigen)
+ # Amaranth HDL (previously nMigen)
 
 The Amaranth project provides an open-source toolchain for developing hardware based on synchronous digital logic using the Python programming language, as well as [evaluation board definitions][amaranth-boards], a [System on Chip toolkit][amaranth-soc], and more. It aims to be easy to learn and use, reduce or eliminate common coding mistakes, and simplify the design of complex hardware with reusable components.
 

docs/lang.rst

@@ -172,6 +172,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.dsl.SyntaxWarning)
+
    .. doctest::
 
       >>> fencepost = C(256, range(256))
@@ -182,6 +190,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::