From 342fd5f8bdc1b447d320fa5dc2a3b14fba8be172 Mon Sep 17 00:00:00 2001
From: Catherine <whitequark@whitequark.org>
Date: Mon, 27 Feb 2023 18:50:47 +0000
Subject: [PATCH] docs: fix doctests and run them in CI workflow.

---
 .github/workflows/main.yaml | 17 +++++++++++------
 docs/lang.rst               |  3 ++-
 docs/requirements.txt       |  2 +-
 3 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
index bf767fd..9fb941b 100644
--- a/.github/workflows/main.yaml
+++ b/.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
diff --git a/docs/lang.rst b/docs/lang.rst
index 06c0c46..1e0459b 100644
--- a/docs/lang.rst
+++ b/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)
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 88045bd..e862aba 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,3 @@
-sphinx~=6.1
+sphinx~=5.3
 sphinxcontrib-platformpicker~=1.3
 sphinx-rtd-theme~=1.2