Document doctest strategy with comprehensive comments

Phase 4 of doctest improvements:
- Add detailed comments in conf.py explaining testing philosophy
- Clarify when to use testcode vs code-block
- Document the selective testing approach for maintainability
- Provide guidance for future contributors

The strategy balances automatic validation with documentation readability,
testing complete examples while keeping fragments illustrative.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: robtaylor

docs/conf.py

@@ -96,6 +96,28 @@
 ]
 
 # 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