docs: fix doctests and run them in CI workflow.

Author: whitequark

.github/workflows/main.yaml

@@ -1,7 +1,4 @@
-on:
-  push: {}
-  pull_request:
-    types: [opened, reopened, synchronize]
+on: [push, pull_request]
 name: CI
 jobs:
   test:
@@ -14,8 +11,14 @@ jobs:
         - '3.9'
         - '3.10'
         - '3.11'
-        - '3.12-dev'
         - 'pypy-3.7-v7.3.3'
+        allow-failure:
+        - false
+        include:
+        - python-version: '3.12-dev'
+          allow-failure: true
+    continue-on-error: '${{ matrix.allow-failure }}'
+    name: 'test (${{ matrix.python-version }})'
     steps:
     - name: Check out source code
       uses: actions/checkout@v3
@@ -32,8 +35,9 @@ jobs:
         sudo apt-get update
         sudo apt-get install yices2
         pip install coverage codecov
-        pip install 'yowasp-yosys==0.20.dev398' # latest version that works on Python 3.7
+        pip install yowasp-yosys==0.20.* # last version compatible with Python 3.7
         pip install -e .[builtin-yosys]
+        pip install -r docs/requirements.txt
     - name: Preserve Wasm cache
       uses: actions/cache@v3
       with:
@@ -47,6 +51,7 @@ jobs:
         export PYTHONWARNINGS=error
         python -m coverage run -m unittest discover -t . -s tests
         unset PYTHONWARNINGS
+        sphinx-build -b doctest docs/ docs/_build
         codecov
   document:
     runs-on: ubuntu-latest

docs/lang.rst

@@ -800,7 +800,7 @@ Every signal included in the target of an assignment becomes a part of the domai
 
    Clearly, Amaranth code that drives a single bit of a signal from two different domains does not describe a meaningful circuit. However, driving two different bits of a signal from two different domains does not inherently cause such a conflict. Would Amaranth accept the following code?
 
-   .. testcode::
+   .. code-block::
 
       e = Signal(2)
       m.d.comb += e[0].eq(0)
@@ -945,6 +945,7 @@ Signals in the combinatorial :ref:`control domain <lang-domains>` change wheneve
 Consider the following code:
 
 .. testsetup::
+
    en = Signal()
    b = Signal(8)
 

docs/requirements.txt

@@ -1,3 +1,3 @@
-sphinx~=6.1
+sphinx~=5.3
 sphinxcontrib-platformpicker~=1.3
 sphinx-rtd-theme~=1.2