Add doctest infrastructure and validate code examples

docs/architecture.rst

@@ -58,13 +58,9 @@ Design Flow in Detail
 
 You write your design in Python using Amaranth HDL and ChipFlow signatures:
 
-.. code-block:: python
-
-    from chipflow_lib.platforms import UARTSignature, GPIOSignature
-    from amaranth import Module
-    from amaranth.lib.wiring import Component, Out
+.. testcode::
 
-    class MySoC(Component):
+    class MySoC(wiring.Component):
         def __init__(self):
             super().__init__({
                 "uart": Out(UARTSignature()),
@@ -76,6 +72,11 @@ You write your design in Python using Amaranth HDL and ChipFlow signatures:
             # Your design logic here
             return m
 
+    # Verify the design can be instantiated
+    design = MySoC()
+    assert hasattr(design, 'uart')
+    assert hasattr(design, 'gpio')
+
 2. Signatures Add Metadata
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/chipflow-toml-guide.rst

@@ -14,7 +14,7 @@ Let's start with a typical example:
    # Assert that example-chipflow.toml matches the current config schema. If
    # this test fails, then its likely that the content in this file will need
    # to be updated.
-   from chipflow_lib.config import _parse_config_file
+   from chipflow_lib.config.parser import _parse_config_file
    _parse_config_file("docs/example-chipflow.toml")
 
 ``[chipflow]`` table

docs/conf.py

@@ -108,6 +108,42 @@
     ("Members", "params_style"), # `amaranth.lib.wiring` signature members
 ]
 
+# Doctest configuration
+#
+# Strategy: Selective testing with infrastructure
+# ------------------------------------------------
+# We use Sphinx doctest extension to validate code examples in our documentation.
+# The approach balances completeness with maintainability:
+#
+# 1. Complete, runnable examples use `.. testcode::` and are validated automatically
+# 2. Illustrative code fragments remain as `.. code-block::` for readability
+# 3. Global setup (below) provides common imports to reduce boilerplate
+#
+# When to convert an example to testcode:
+# - Complete class definitions that can be instantiated
+# - Signature usage examples showing public API
+# - Self-contained examples using only documented public APIs
+#
+# When to keep as code-block:
+# - Incomplete fragments (e.g., just showing part of __init__)
+# - Examples requiring external dependencies (chipflow_digital_ip)
+# - Pseudo-code or conceptual illustrations
+#
+# Run tests with: pdm test-docs
+
+doctest_global_setup = """
+from pathlib import Path
+from amaranth import Module
+from amaranth.lib import wiring
+from amaranth.lib.wiring import In, Out, connect, flipped
+from amaranth_soc import csr, wishbone
+from chipflow_lib.platforms import (
+    UARTSignature, GPIOSignature, SPISignature, I2CSignature,
+    QSPIFlashSignature, JTAGSignature,
+    IOTripPoint, Sky130DriveMode,
+    SoftwareDriverSignature, attach_data, SoftwareBuild
+)
+"""
 
 rst_prolog = """
 .. role:: py(code)

docs/using-pin-signatures.rst

@@ -34,11 +34,9 @@ Using Pin Signatures in Your Top-Level Design
 
 Pin signatures are used when defining your top-level component's interface:
 
-.. code-block:: python
-
-    from amaranth.lib.wiring import Out
-    from chipflow_lib.platforms import UARTSignature, GPIOSignature, QSPIFlashSignature
+.. testcode::
 
+    # Define a simple SoC with external interfaces
     class MySoC(wiring.Component):
         def __init__(self):
             super().__init__({
@@ -47,6 +45,12 @@ Pin signatures are used when defining your top-level component's interface:
                 "flash": Out(QSPIFlashSignature()),
             })
 
+    # Verify the component can be instantiated
+    soc = MySoC()
+    assert hasattr(soc, 'uart')
+    assert hasattr(soc, 'gpio')
+    assert hasattr(soc, 'flash')
+
 These signatures tell ChipFlow:
 
 - How to connect your design to the physical pins of your chip