Add examples documentation and fix docs build issues

.github/docs-review-prompt.md

@@ -0,0 +1,78 @@
+# Documentation Review Prompt
+
+Review the ChipFlow documentation for quality, accuracy, and consistency.
+
+## Context
+
+ChipFlow is a platform for designing and building hardware systems (SoCs) using Python and Amaranth HDL. The documentation covers:
+
+- **chipflow-lib**: The main Python library and CLI tool
+- **amaranth**: The hardware description language
+- **amaranth-soc**: System-on-Chip design library
+- **chipflow-examples**: Example designs (minimal SoC, MCU SoC)
+
+## Review Criteria
+
+### 1. Technical Accuracy
+
+- Do code examples actually work with the current API?
+- Are command-line examples correct (`pdm chipflow ...`, etc.)?
+- Are configuration file examples (`chipflow.toml`) valid?
+- Do cross-references to other documentation sections resolve correctly?
+- Are version numbers and URLs up to date?
+
+### 2. Consistency
+
+- Is terminology used consistently? (e.g., "SoC" vs "System-on-Chip", "pin" vs "port")
+- Are code style conventions consistent across examples?
+- Do similar concepts use similar explanations across different pages?
+- Are file paths and directory structures described consistently?
+
+### 3. Flow and Organization
+
+- Does the getting-started guide provide a clear path for new users?
+- Are prerequisites clearly stated before each section?
+- Do topics build logically on each other?
+- Are advanced topics appropriately separated from beginner content?
+- Is the navigation structure (toctree) logical?
+
+### 4. Completeness
+
+- Are all major features documented?
+- Are error messages and troubleshooting covered?
+- Are environment variables and configuration options documented?
+- Are there gaps in the examples that would confuse users?
+
+### 5. Links and References
+
+- Do internal cross-references (`:doc:`, `:ref:`, `:class:`) work?
+- Are external URLs valid and pointing to the correct resources?
+- Is the relationship between chipflow-lib, amaranth, and amaranth-soc clear?
+
+## Output Format
+
+Provide your findings in this structure:
+
+```
+## Summary
+[Overall assessment of documentation quality - 1-2 sentences]
+
+## Issues Found
+
+### Critical
+[Issues that would prevent users from following the documentation]
+
+### Major
+[Significant inaccuracies or confusing sections]
+
+### Minor
+[Small improvements or nitpicks]
+
+## Recommendations
+[Top 3-5 actionable improvements]
+
+## Files Reviewed
+[List of files examined]
+```
+
+If no issues are found in a category, note "None found" rather than omitting it.

.github/workflows/docs-review.yml

@@ -0,0 +1,175 @@
+name: Documentation Review
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '*.md'
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '*.md'
+  workflow_dispatch:
+
+jobs:
+  review-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install PDM
+        run: pip install pdm
+
+      - name: Install dependencies
+        run: pdm install
+
+      - name: Build documentation
+        run: pdm run docs
+        continue-on-error: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Review documentation with Claude Code
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          # Create the review prompt
+          cat > /tmp/review-prompt.txt << 'PROMPT_EOF'
+          Review the ChipFlow documentation for quality, accuracy, and consistency.
+
+          ## Context
+          ChipFlow is a platform for designing and building hardware systems (SoCs) using Python and Amaranth HDL.
+
+          ## Review the following:
+
+          1. **Technical Accuracy**
+             - Do code examples work with the current API?
+             - Are command-line examples correct?
+             - Are configuration file examples valid?
+
+          2. **Consistency**
+             - Is terminology used consistently?
+             - Are code style conventions consistent?
+
+          3. **Flow and Organization**
+             - Does the getting-started guide provide a clear path?
+             - Do topics build logically on each other?
+
+          4. **Completeness**
+             - Are all major features documented?
+             - Are there gaps that would confuse users?
+
+          ## Output Format
+          Provide findings as:
+
+          ## Summary
+          [1-2 sentence assessment]
+
+          ## Issues Found
+
+          ### Critical
+          [Issues preventing users from following docs]
+
+          ### Major
+          [Significant inaccuracies]
+
+          ### Minor
+          [Small improvements]
+
+          ## Recommendations
+          [Top 3-5 actionable improvements]
+
+          Focus on docs/source/ and .md files. Report actual issues only.
+          PROMPT_EOF
+
+          # Run Claude Code in print mode (non-interactive)
+          claude --print "$(cat /tmp/review-prompt.txt)" > review-results.txt 2>&1 || true
+
+          # Show the results
+          cat review-results.txt
+
+      - name: Process review results
+        id: process-review
+        run: |
+          if [ -f review-results.txt ] && [ -s review-results.txt ]; then
+            # Use heredoc to handle multiline output
+            {
+              echo 'review<<EOF'
+              cat review-results.txt
+              echo 'EOF'
+            } >> $GITHUB_OUTPUT
+          else
+            echo "review=Documentation review did not produce output" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Comment on PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const review = process.env.REVIEW_CONTENT;
+
+            // Find existing comment from this workflow
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(comment =>
+              comment.user.type === 'Bot' &&
+              comment.body.includes('## 📚 Documentation Review')
+            );
+
+            const body = `## 📚 Documentation Review
+
+            ${review}
+
+            ---
+            *This review was automatically generated by Claude Code*`;
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: body
+              });
+            }
+        env:
+          REVIEW_CONTENT: ${{ steps.process-review.outputs.review }}
+
+      - name: Upload review results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: docs-review-results
+          path: review-results.txt
+          retention-days: 30

CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ChipFlow is a platform for designing and building hardware systems, particularly System-on-Chips (SoCs), using Python. This repository contains documentation for the ChipFlow ecosystem, which includes:
+
+- Hardware description libraries (Amaranth HDL)
+- Support for SoC design (amaranth-soc)
+- ChipFlow-specific libraries and platforms
+- Example designs (minimal SoC, MCU SoC)
+
+## Build Commands
+
+- **Install dependencies**: `pdm install`
+- **Build documentation**: `pdm run docs`
+- **Auto-rebuild documentation**: `pdm run autodocs`
+- **View documentation**: Visit http://localhost:8000 when running autodocs
+
+## Testing
+
+- **Python tests**: `pytest`
+- **Run specific test**: `pytest tests/test_file.py::test_function_name`
+
+## Code Style Guidelines
+
+- **Python**: PEP-8 style, Python 3.10+
+- **Linting**: `ruff check .`
+- **Type checking**: `pyright`
+
+## Repository Structure
+
+- **docs/source/**: Documentation source files in reStructuredText format
+- **vendor/**: Cloned repositories for documentation integration
+  - amaranth: Hardware description library
+  - amaranth-soc: SoC design library
+  - chipflow-lib: ChipFlow platform libraries
+- **chipflow-examples/**: Example ChipFlow designs
+  - minimal/: Minimal SoC with RISC-V core
+  - mcu_soc/: MCU-style SoC with peripherals
+
+## Documentation Management
+
+The `copy-docs.sh` script clones and integrates documentation from:
+- amaranth-lang/amaranth
+- chipflow/amaranth-soc
+- chipflow/chipflow-lib
+
+Documentation is built using Sphinx with extensions for:
+- Multi-project documentation
+- API documentation
+- Custom styling
+- Interactive elements

docs/source/conf.py

@@ -7,7 +7,7 @@
 top_path = Path('../../')
 sys.path.append(str((top_path / 'tools').absolute()))
 
-from tools import copy_docs
+from copy_docs import copy_docs
 
 # Repos we will be assembling
 repos = [
@@ -22,8 +22,29 @@
 
 # add our repos to path
 for r in repo_list:
+    print(f"copy_docs: Adding {str(r)} to sys.path")
     sys.path.append(str(r))
 
+# Create platform-api.rst in docs/source/ (outside chipflow-lib to avoid copy_docs overwriting)
+# This file points to the autoapi-generated index
+Path('platform-api.rst').write_text("""Platform API Reference
+======================
+
+This section provides the API reference for the ChipFlow platform library.
+
+.. toctree::
+   :maxdepth: 3
+
+   chipflow-lib/autoapi/chipflow/index
+""")
+
+# Update chipflow-lib/index.rst to point to the platform-api.rst outside chipflow-lib/
+chipflow_lib_index = Path('chipflow-lib/index.rst')
+if chipflow_lib_index.exists():
+    content = chipflow_lib_index.read_text()
+    content = content.replace('platform-api', '/platform-api')
+    chipflow_lib_index.write_text(content)
+
 # -- Project information
 
 project = 'ChipFlow'
@@ -41,7 +62,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx_copybutton',
-    'myst_parser',
+    # 'myst_parser',
     'sphinx.ext.todo',
     'sphinx.ext.napoleon',
     'sphinx.ext.autodoc',
@@ -50,6 +71,7 @@
     'sphinxcontrib.yowasp_wavedrom',
     'sphinxext.rediraffe',
     'autoapi.extension',
+    'sphinx_design',
 ]
 
 rst_prolog = """
@@ -63,6 +85,11 @@
    :language: python
 """
 
+rst_epilog = """
+.. |required| replace:: :bdg-primary-line:`Required`
+.. |optional| replace:: :bdg-secondary-line:`Optional`
+"""
+
 html_theme = 'furo'
 html_logo = 'chipflow-lib/_assets/chipflow-logo.svg'
 html_title = "ChipFlow Platform Documentation"
@@ -93,11 +120,17 @@
     'imported-members',
 ]
 autoapi_root = "chipflow-lib/autoapi"
+autoapi_add_toctree_entry = False  # We'll manually add to toctree in platform-api.rst
+autoapi_ignore = [
+    "*/chipflow_lib/*",  # Backward compatibility shim
+]
 
 # Exclude autoapi templates and in-progress stuff
 exclude_patterns = [
     autoapi_template_dir,
     "chipflow-lib/unfinished",
+    "chipflow-lib/UNFINISHED_IDEAS.md",
+    "chipflow-lib/platform-api.rst",  # We use /platform-api.rst at root instead
     "amaranth/cover.rst",
     "amaranth-soc/cover.rst",
 ]