Add examples documentation and fix docs build issues

[robtaylor]

Summary

• Add documentation for chipflow-examples:

  • examples/index.rst: Overview of available examples
  • examples/getting-started.rst: Setup and first build guide
  • examples/minimal.rst: Minimal SoC example documentation
  • examples/mcu-soc.rst: MCU SoC example documentation

• Fix documentation build issues:

  • Add sphinx_design extension for badge roles (|required|, |optional|)
  • Add rst_epilog with substitution definitions
  • Add chipflow package to autoapi_dirs for complete API docs
  • Replace platform-api.rst autodoc directives with static content (autodoc requires chipflow to be installed)
  • Exclude UNFINISHED_IDEAS.md from build

• Reorganize index.rst:

  • Add "Getting Started" section with tutorial
  • Add "Examples" section
  • Rename existing section to "Reference"

• Add CI workflow for documentation review with Claude Code:

  • Triggers on PRs and pushes affecting docs/** or *.md files
  • Builds documentation and runs Claude Code to review for:
    • Technical accuracy (code examples, CLI commands)
    • Consistency (terminology, code style)
    • Flow and organization (logical structure)
    • Completeness (feature coverage, gaps)
  • Posts review results as PR comments
  • Requires ANTHROPIC_API_KEY secret to be configured

• Add CLAUDE.md with project instructions

Test plan

• Build documentation with pdm run docs
• Verify examples pages render correctly
• Verify no new RST errors (remaining warnings are from Python stdlib docstrings in AutoAPI)
• Configure ANTHROPIC_API_KEY secret in repository settings to enable CI workflow

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.6.3
🚀 View preview at https://chipflow-docs.docs.chipflow-infra.com/pr-preview/pr-15/
Built to branch gh-pages at 2025-12-17 01:55 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

📚 Documentation Review

Summary

The ChipFlow documentation is well-organized with clear progressive examples, but has significant command syntax inconsistencies and references to external documentation that doesn't exist in the repository.

Issues Found

Critical

1. Inconsistent PDM command syntax across guides:

   • tutorial-intro-chipflow-platform.rst uses: pdm run chipflow <command>
   • examples/getting-started.rst, examples/minimal.rst, examples/mcu-soc.rst use: pdm chipflow <command> and shortcuts like pdm submit, pdm sim-check
   • configurator/index.rst uses bare commands: chipflow sim build, chipflow sim run, chipflow silicon submit

   Users following different guides will encounter command failures.

2. Broken documentation references:

   • examples/getting-started.rst lines 130-131 reference :doc:../chipflow-lib/chipflow-toml-guide and `:doc:`../chipflow-lib/simulation-guide
   • The chipflow-lib/ directory doesn't exist in docs/source/ (pulled during build via copy_docs)
   • Makes local development and verification difficult

3. Incomplete workflow reference:

   • tutorial-intro-chipflow-platform.rst:530 directs users to :doc:examples/getting-started`` for "full submission workflow"
   • That guide only shows the submit command, not a complete workflow explanation

Major

1. Missing chipflow-lib documentation source: Multiple references to chipflow-lib/getting-started, chipflow-lib/index in index.rst, but sources aren't in the repository - they're copied at build time from external repos.

2. Python version inconsistency:

   • tutorial-intro-chipflow-platform.rst:559: "Python 3.11 or greater"
   • examples/getting-started.rst:11: "Python 3.11+"
   • CLAUDE.md: "Python 3.10+"

3. Limited troubleshooting coverage: Tutorial troubleshooting section (lines 555-560) only covers Python version issues, missing common problems like PDM failures, board connections, serial ports, and simulation build errors.

Minor

1. Inconsistent terminology: "System-on-Chip" vs "System-on-a-Chip" used interchangeably

2. Incomplete memory map explanation: minimal.rst memory map doesn't explain the 1MB boot offset, CSR address allocation strategy, or how users should choose addresses

3. Code block formatting varies: Mix of .. code-block:: python, .. code-block:: bash, :bash:\command`, and .. code-block:: text`

4. Outdated roadmap: Tutorial mentions "Silicon build API" as future work, but silicon submission is already documented in getting-started.rst

5. Missing navigation links: Example docs don't link back to tutorials, unclear reading order

Recommendations

1. Standardize command syntax immediately - Choose one pattern (pdm run chipflow or PDM shortcuts) and update all docs consistently. Document the correct pattern in CLAUDE.md.

2. Fix documentation references - Either include stub files for chipflow-lib guides with "Coming soon" messages, or use external links until available. Add README explaining copy_docs build process.

3. Expand troubleshooting - Add sections for PDM installation, board connections/permissions, serial ports, and simulation errors. Link to GitHub Discussions.

4. Standardize Python version - Update all references to consistently state "Python 3.11+" minimum.

5. Improve navigation - Add prerequisite admonitions and "Next steps" sections. Create clear learning path: Configurator → Getting Started → Minimal → MCU SoC → Tutorial.

---

This review was automatically generated by Claude Code

[github-actions]

📖 Documentation Preview

✅ Preview is live!

🔗 View preview

---

_{Built from commit f4f3c51}