Add doctest infrastructure and validate code examples

[robtaylor]

Summary

This PR adds doctest infrastructure to validate code examples in the documentation and fixes the existing failing test.

Branched from: refactor/restructure-codebase (as requested)

Changes Made

Phase 1: Fix Existing Failing Test ✅

• Fixed import path in chipflow-toml-guide.rst doctest
• Changed from chipflow_lib.config to chipflow_lib.config.parser
• Existing doctest now passes

Phase 2: Add Doctest Infrastructure ✅

• Added doctest_global_setup in docs/conf.py
• Provides common imports for all doctest blocks:
  • Amaranth modules (Module, wiring, In, Out, etc.)
  • ChipFlow signatures (UART, GPIO, SPI, etc.)
  • Other common utilities
• Reduces boilerplate in test examples

Phase 3: Convert Strategic Examples ✅

• Converted 2 complete examples from .. code-block:: to .. testcode::
• Added assertions to verify classes can be instantiated
• Examples chosen: complete, self-contained, using only public APIs
• Examples converted:
  • using-pin-signatures.rst: MySoC basic example
  • architecture.rst: MySoC with elaborate() example

Phase 4: Document Testing Strategy ✅

• Added comprehensive comments in conf.py explaining the approach
• Clarified when to use testcode vs code-block
• Documented selective testing philosophy

Testing Strategy

The approach balances automatic validation with documentation readability:

1. Complete, runnable examples use .. testcode:: → validated automatically
2. Illustrative fragments remain as .. code-block:: → kept for readability
3. Global setup provides common imports → reduces boilerplate

Test Results

All doctests pass:

Doctest summary
===============
    3 tests
    0 failures in tests
    0 failures in setup code
    0 failures in cleanup code

Run tests with: pdm test-docs

Benefits

✅ Code examples are automatically validated against API changes
✅ CI can catch documentation that breaks with code changes
✅ Maintains documentation readability (no excessive test boilerplate)
✅ Clear guidance for contributors on which examples to test

What's Not Tested

By design, the following remain as illustrative code-block examples:

• Incomplete code fragments (partial __init__ calls, etc.)
• Examples requiring external deps (chipflow_digital_ip)
• Pseudo-code/conceptual illustrations
• Implementation details (internal APIs)

This keeps docs readable while ensuring core public API examples are validated.

🤖 Generated with Claude Code

[github-actions]

Tests	Skipped	Failures	Errors	Time
41	4 💤	0 ❌	0 🔥	20.972s ⏱️

[github-actions]

PR Preview Action v1.6.2
🚀 View preview at https://chipflow-lib.docs.chipflow-infra.com/pr-preview/pr-145/
Built to branch gh-pages at 2025-10-28 14:31 UTC. Preview will be ready when the GitHub Pages deployment is complete.