Fix toctree hierarchy for chipflow-lib documentation

[robtaylor]

Summary

• Fix heading levels in chipflow-toml-guide.rst so config options appear as subsections
• Rename "Intro to chipflow.toml" to "chipflow.toml Reference"
• Platform API Reference now properly nested under ChipFlow Library Documentation
• Add cross-references in using-pin-signatures.rst to link to API docs

Problem

1. The toctree was showing incorrect hierarchy:

   • project_name, clock_domains, process, package appeared as top-level entries
   • Platform API Reference appeared outside ChipFlow Library Documentation

2. References to classes like UARTSignature, GPIOSignature, IOTripPoint were plain text instead of links to the API documentation

Solution

Added post-processing in copy_docs.py to fix issues after copying from vendor:

• Changed === underlines to ^^^ for config option headings
• Renamed document title for clarity
• Convert plain text references like `UARTSignature()` to proper Sphinx cross-references like :py:class:~chipflow.platform.UARTSignature``

Result

• Correct toctree hierarchy with config options nested under their sections
• Pin signature classes now link to their API documentation
• Warnings reduced from 45 to 13

🤖 Generated with Claude Code

[github-actions]

📖 Documentation Preview

✅ Preview is live!

🔗 View preview

---

_{Built from commit 2e7a190}

[github-actions]

📖 Documentation Preview

✅ Preview is live!

🔗 View preview

---

_{Built from commit c86e886}

[github-actions]

📖 Documentation Preview

✅ Preview is live!

🔗 View preview

---

_{Built from commit 83a3ab4}

[github-actions]

📖 Documentation Preview

✅ Preview is live!

🔗 View preview

---

_{Built from commit 56055de}

[github-actions]

📚 Documentation Review

Let me just provide the review directly to you:

Summary

The ChipFlow documentation is well-structured and comprehensive, covering getting started guides, examples, and reference documentation. However, there are critical inconsistencies in command syntax between different sections that would confuse users, plus some missing vendor documentation directories and minor terminology issues.

Issues Found

Critical

1. Command Syntax Inconsistency - Examples vs Tutorial

The most serious issue: three different command formats are used across the documentation:

• Examples docs use: pdm chipflow pin lock, pdm sim-check, pdm submit
• Tutorial docs use: pdm run chipflow sim build, pdm run chipflow software
• Configurator docs use: chipflow sim build (no pdm prefix)

Impact: Users won't know which commands are correct, leading to failures.

Files affected:

• docs/source/examples/getting-started.rst:78, 84, 109, 123
• docs/source/examples/minimal.rst:112-114
• docs/source/examples/mcu-soc.rst:171-173
• docs/source/tutorial-intro-chipflow-platform.rst:214, 223, 229, 255, 264, 270-271
• docs/source/configurator/index.rst:67, 76, 85, 90-94

2. Missing Vendor Documentation Directories

The index.rst references chipflow-lib/, amaranth/, amaranth-soc/, and chipflow-digital-ip/ directories that don't exist in the repo. These are generated at build time by copy_docs.py.

Impact: Broken links when viewing raw documentation; dependency on build process.

3. Cross-References to Non-Existent Files

docs/source/examples/getting-started.rst:130-131 links to:

• :doc:../chipflow-lib/chipflow-toml-guide``
• :doc:../chipflow-lib/simulation-guide``

These files don't exist until build time.

Major

4. Python Version Requirement Inconsistency

• examples/getting-started.rst says "Python 3.11+"
• tutorial says "Python 3.11 or greater"
• pyproject.toml specifies <3.13 (meaning 3.12 max)
• CLAUDE.md says "Python 3.10+"

Correct requirement should be: Python 3.11 or 3.12

5. Terminology Inconsistency: System-on-Chip

• index.rst uses "System-on-a-Chip toolkit"
• tutorial uses "SoC (system on chip)"
• examples use "System-on-Chip"

Minor inconsistency in capitalization/hyphenation.

6. Email Typo in Project Metadata

pyproject.toml:5 shows "rob.tayloe@chipflow.io" (likely should be "rob.taylor@chipflow.io")

7. Tutorial May Reference Old Project Structure

tutorial-intro-chipflow-platform.rst uses different commands than the examples docs, suggesting it may be outdated.

Minor

8. README vs CLAUDE.md Command Discrepancy

• README shows pdm docs / pdm autodocs
• CLAUDE.md shows pdm run docs / pdm run autodocs

Both work with PDM, just inconsistent.

9. Potentially Broken Internal Reference

tutorial-intro-chipflow-platform.rst:249 uses :ref:skip to the next section `` but the label may not exist.

10. Unexplained Command

examples/getting-started.rst:45 shows pdm lock -d without explaining what it does.

11-12. Minor formatting issues with URLs and screenshot numbering

Recommendations

Top 5 Actionable Improvements

1. CRITICAL: Standardize Command Syntax

   • Choose ONE format (recommend: pdm <script> for project scripts, pdm run chipflow <command> for chipflow CLI)
   • Update ALL docs consistently
   • Add command reference table

2. CRITICAL: Verify Vendor Documentation Build

   • Test that pdm run docs creates all vendor directories
   • Add note to README explaining vendor docs are built dynamically
   • Add build verification to CI/CD

3. HIGH: Clarify Python Version Requirements

   • Update all docs to say "Python 3.11 or 3.12"
   • Fix CLAUDE.md from "3.10+" to "3.11 or 3.12"

4. MEDIUM: Fix Email Typo

   • Correct pyproject.toml:5 email address
   • Verify support.rst contact info

5. MEDIUM: Add Command Reference Section

   • Create dedicated command reference page
   • Document all available commands with descriptions
   • Link from getting-started guide

Strengths

• Clear, logical organization
• Comprehensive examples (minimal & mcu_soc)
• Good code blocks with syntax highlighting
• Platform-specific instructions
• Visual aids in Configurator section
• Detailed memory maps and configuration examples

The documentation has excellent foundational content but needs immediate attention to command standardization to prevent user confusion.

---

This review was automatically generated by Claude Code

[github-actions]

📖 Documentation Preview

✅ Preview is live!

🔗 View preview

---

_{Built from commit d251aa1}

[github-actions]

📖 Documentation Preview

✅ Preview is live!

🔗 View preview

---

_{Built from commit 0c01b73}