From e3bce037e626053ea3573c601b0f5152be5ca8f3 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 16 Dec 2025 22:14:16 +0000 Subject: [PATCH 1/7] Add examples documentation and fix docs build issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 - Add rst_epilog with |required| and |optional| substitutions - 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 CLAUDE.md with project instructions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 54 +++++++ docs/source/conf.py | 104 +++++++++++++ docs/source/examples/getting-started.rst | 131 ++++++++++++++++ docs/source/examples/index.rst | 33 ++++ docs/source/examples/mcu-soc.rst | 190 +++++++++++++++++++++++ docs/source/examples/minimal.rst | 132 ++++++++++++++++ docs/source/index.rst | 14 +- 7 files changed, 657 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md create mode 100644 docs/source/examples/getting-started.rst create mode 100644 docs/source/examples/index.rst create mode 100644 docs/source/examples/mcu-soc.rst create mode 100644 docs/source/examples/minimal.rst diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..569dbd6 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index e9ceeb6..1846176 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -24,6 +24,101 @@ for r in repo_list: sys.path.append(str(r)) +# Fix platform-api.rst to remove autodoc directives (requires chipflow to be installed) +# Replace with overview content that links to autoapi +platform_api_content = """Platform API Reference +====================== + +This page provides an overview of the ChipFlow platform API. Full API documentation is auto-generated from the source code. + +.. seealso:: + + See the :doc:`autoapi/index` for complete auto-generated API documentation. + +Platforms +--------- + +The ChipFlow library provides several platform implementations for different build targets: + +**SimPlatform** (``chipflow.platform.sim``) + Platform for building and running CXXRTL simulations. Use this during development to test your design. + +**SiliconPlatform** (``chipflow.platform.silicon``) + Platform for targeting ASIC fabrication. Supports various foundry processes including SKY130, GF180, GF130BCD, and IHP_SG13G2. + +**SoftwarePlatform** (``chipflow.platform.software``) + Platform for building RISC-V software to run on your design. + +Build Steps +----------- + +Steps are the building blocks of the ChipFlow build system: + +**SimStep** (``chipflow.platform.sim_step``) + Handles simulation workflow: building the simulator, running simulations, and checking results. + +**SiliconStep** (``chipflow.platform.silicon_step``) + Handles ASIC preparation: elaborating designs to RTLIL and submitting to the ChipFlow cloud builder. + +**SoftwareStep** (``chipflow.platform.software_step``) + Handles RISC-V software compilation. + +**BoardStep** (``chipflow.platform.board_step``) + Handles board-level operations. + +IO Signatures +------------- + +IO Signatures define standard interfaces for your design. They provide a consistent way to connect peripherals and specify electrical characteristics. + +Base Signatures +~~~~~~~~~~~~~~~ + +- **IOSignature** - Base class for all IO signatures +- **OutputIOSignature** - For output-only signals +- **InputIOSignature** - For input-only signals +- **BidirIOSignature** - For bidirectional signals + +Protocol Signatures +~~~~~~~~~~~~~~~~~~~ + +Pre-defined signatures for common protocols: + +- **UARTSignature** - UART serial interface +- **GPIOSignature** - General purpose I/O +- **SPISignature** - SPI bus interface +- **I2CSignature** - I2C bus interface +- **QSPIFlashSignature** - Quad SPI flash interface +- **JTAGSignature** - JTAG debug interface + +IO Configuration +---------------- + +**IOModel** + Configures electrical characteristics of IO pads (drive mode, trip point, inversion). + +**IOModelOptions** + Available options for IO configuration. + +**IOTripPoint** + Voltage threshold configuration for input signals. + +Utility Functions +----------------- + +**setup_amaranth_tools()** + Sets up the Amaranth toolchain for your environment. + +**top_components()** + Returns dictionary of instantiated top-level components from configuration. + +**get_software_builds()** + Returns software build configurations from the design. +""" +platform_api_path = Path('chipflow-lib/platform-api.rst') +if platform_api_path.exists(): + platform_api_path.write_text(platform_api_content) + # -- Project information project = 'ChipFlow' @@ -50,6 +145,7 @@ 'sphinxcontrib.yowasp_wavedrom', 'sphinxext.rediraffe', 'autoapi.extension', + 'sphinx_design', ] rst_prolog = """ @@ -63,6 +159,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" @@ -80,6 +181,8 @@ autodoc_typehints = 'description' autoapi_dirs = [ + top_path / "vendor/chipflow-lib/chipflow_lib/platforms", + top_path / "vendor/chipflow-lib/chipflow_lib", top_path / "vendor/chipflow-lib/chipflow", ] autoapi_generate_api_docs = True @@ -98,6 +201,7 @@ exclude_patterns = [ autoapi_template_dir, "chipflow-lib/unfinished", + "chipflow-lib/UNFINISHED_IDEAS.md", "amaranth/cover.rst", "amaranth-soc/cover.rst", ] diff --git a/docs/source/examples/getting-started.rst b/docs/source/examples/getting-started.rst new file mode 100644 index 0000000..b0fccba --- /dev/null +++ b/docs/source/examples/getting-started.rst @@ -0,0 +1,131 @@ +Getting Started with ChipFlow Examples +====================================== + +This guide will walk you through setting up the ChipFlow examples repository and running your first chip build. + +Prerequisites +------------- + +Before you begin, ensure you have the following installed: + +- **Python 3.11+**: `Python Downloads `_ +- **Git**: `Git Downloads `_ +- **PDM**: `PDM Installation `_ + +We also recommend: + +- **VS Code**: `VS Code Downloads `_ +- **GitHub Desktop**: `GitHub Desktop Downloads `_ + +Clone the Repository +-------------------- + +Using Git command line: + +.. code-block:: bash + + git clone https://github.com/ChipFlow/chipflow-examples.git + cd chipflow-examples + +Or using GitHub Desktop: + +1. Go to the `chipflow-examples repository `_ +2. Click the green "Code" button +3. Select "Open with GitHub Desktop" +4. Follow the prompts to clone + +Install Dependencies +-------------------- + +Once you have the repository cloned, install the dependencies: + +.. code-block:: bash + + cd chipflow-examples + pdm lock -d + pdm install + +Set Up Your API Key +------------------- + +To submit designs to the ChipFlow cloud builder, you need an API key: + +1. Go to https://build.chipflow.org/user/detail +2. Click "Create/Refresh API Key" +3. Copy your new API key (you won't see it again!) + +Create a ``.env`` file in the ``chipflow-examples`` directory: + +.. code-block:: bash + + echo "CHIPFLOW_API_KEY=your_api_key_here" > .env + +Replace ``your_api_key_here`` with your actual API key. + +Running Your First Build +------------------------ + +Let's try the ``minimal`` example: + +.. code-block:: bash + + cd minimal + +First, lock the pin assignments: + +.. code-block:: bash + + pdm chipflow pin lock + +Run the simulation to test the design: + +.. code-block:: bash + + pdm sim-check + +You should see the simulation being built and run, with test output like: + +.. code-block:: text + + -- build_sim_cxxrtl + -- build_sim + pdm chipflow software + -- gather_dependencies + -- build_software_elf + -- build_software + cd build/sim && ./sim_soc + SoC type: CA7F100F + Flash ID: CA7CA7FF + Quad mode + Event logs are identical + +Submitting to ChipFlow +---------------------- + +Once your simulation passes, submit your design to be built: + +.. code-block:: bash + + pdm submit + +This returns a build URL where you can monitor progress: + +.. code-block:: text + + INFO:chipflow_lib.steps.silicon:Submitting c23dab6-dirty for project chipflow-examples-minimal + INFO:chipflow_lib.steps.silicon:Submitted design: {'build_id': '3f51a69c-b3e3-4fd3-88fd-52826ac5e5dd'} + Design submitted successfully! Build URL: https://build.chipflow.org/build/3f51a69c-b3e3-4fd3-88fd-52826ac5e5dd + +To stream build logs to your terminal: + +.. code-block:: bash + + pdm submit --wait + +Next Steps +---------- + +- Explore the :doc:`minimal` example to understand the basic structure +- Try the :doc:`mcu-soc` example for a more complete design +- Read the :doc:`../chipflow-lib/chipflow-toml-guide` to understand configuration options +- Check the :doc:`../chipflow-lib/simulation-guide` for simulation details diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst new file mode 100644 index 0000000..2eb6e14 --- /dev/null +++ b/docs/source/examples/index.rst @@ -0,0 +1,33 @@ +ChipFlow Examples +================= + +The `chipflow-examples `_ repository contains example designs demonstrating how to build chips using the ChipFlow platform. + +These examples show you how to: + +- Structure a ChipFlow project +- Configure your design with ``chipflow.toml`` +- Run simulations to test your design +- Submit your design to the ChipFlow cloud builder + +Available Examples +------------------ + +**Minimal SoC** (:doc:`minimal`) + A minimal System-on-Chip with a RISC-V core. This is the simplest starting point for understanding ChipFlow projects. + +**MCU SoC** (:doc:`mcu-soc`) + A more complete MCU-style SoC with additional peripherals. Demonstrates a more realistic design with GPIO, UART, and other interfaces. + +Getting Started +--------------- + +See :doc:`getting-started` for instructions on how to clone the examples repository and run your first chip build. + +.. toctree:: + :maxdepth: 2 + :hidden: + + getting-started + minimal + mcu-soc diff --git a/docs/source/examples/mcu-soc.rst b/docs/source/examples/mcu-soc.rst new file mode 100644 index 0000000..9d5f110 --- /dev/null +++ b/docs/source/examples/mcu-soc.rst @@ -0,0 +1,190 @@ +MCU SoC Example +=============== + +The ``mcu_soc`` example demonstrates a more complete microcontroller-style System-on-Chip with multiple peripherals, targeting the IHP SG13G2 process. + +Overview +-------- + +This example creates a full-featured MCU with: + +- **CV32E40P RISC-V CPU** - A 32-bit RISC-V processor with debug support +- **JTAG Debug Module** - Full debug capabilities via JTAG interface +- **QSPI Flash** - External flash memory for code storage +- **SRAM** - 2KB of on-chip RAM +- **Multiple GPIO Banks** - 2 banks of 8-bit GPIO (16 total) +- **Multiple UARTs** - 2 UART interfaces +- **SPI Controllers** - 3 user SPI interfaces +- **I2C Controllers** - 2 I2C bus interfaces +- **PWM Controllers** - 10 motor PWM outputs + +Project Structure +----------------- + +.. code-block:: text + + mcu_soc/ + ├── chipflow.toml # Project configuration + ├── design/ + │ ├── design.py # Main SoC design + │ ├── ips/ # Custom IP cores (PWM, etc.) + │ ├── openocd/ # OpenOCD debug configuration + │ ├── software/ # Firmware source code + │ ├── steps/ # Custom build steps + │ └── tests/ # Test reference data + └── README.md + +Configuration +------------- + +The ``chipflow.toml`` targets the IHP SG13G2 process with a PGA144 package: + +.. code-block:: toml + + [chipflow] + project_name = "chipflow-examples" + + [chipflow.top] + soc = "design.design:MySoC" + + [chipflow.steps] + board = "design.steps.board:MyBoardStep" + + [chipflow.silicon] + process = "ihp_sg13g2" + package = "pga144" + + [chipflow.test] + event_reference = "design/tests/events_reference.json" + +Peripheral Configuration +------------------------ + +The MCU SoC uses parameterized peripheral counts: + +.. code-block:: python + + self.user_spi_count = 3 # 3 SPI interfaces + self.i2c_count = 2 # 2 I2C interfaces + self.motor_count = 10 # 10 PWM channels + self.uart_count = 2 # 2 UART interfaces + self.gpio_banks = 2 # 2 GPIO banks + self.gpio_width = 8 # 8 bits per bank + +Interface Declaration +--------------------- + +The design dynamically creates interfaces based on peripheral counts: + +.. code-block:: python + + interfaces = { + "flash": Out(QSPIFlashSignature()), + "cpu_jtag": Out(JTAGSignature()) + } + + for i in range(self.user_spi_count): + interfaces[f"user_spi_{i}"] = Out(SPISignature()) + + for i in range(self.i2c_count): + interfaces[f"i2c_{i}"] = Out(I2CSignature()) + + for i in range(self.uart_count): + interfaces[f"uart_{i}"] = Out(UARTSignature()) + + for i in range(self.gpio_banks): + interfaces[f"gpio_{i}"] = Out(GPIOSignature(pin_count=self.gpio_width)) + +Memory Map +---------- + +.. list-table:: + :header-rows: 1 + + * - Region + - Base Address + - Description + * - SPI Flash + - ``0x00000000`` + - Code storage + * - SRAM + - ``0x10000000`` + - 2KB on-chip RAM + * - Debug + - ``0xa0000000`` + - Debug module + * - SPI Flash CSR + - ``0xb0000000`` + - Flash control registers + * - GPIO CSR + - ``0xb1000000`` + - GPIO registers (offset ``0x100000`` per bank) + * - UART CSR + - ``0xb2000000`` + - UART registers (offset ``0x100000`` per UART) + * - SoC ID CSR + - ``0xb4000000`` + - SoC identification + * - User SPI CSR + - ``0xb5000000`` + - SPI registers (offset ``0x100000`` per SPI) + * - I2C CSR + - ``0xb6000000`` + - I2C registers (offset ``0x100000`` per I2C) + * - Motor PWM CSR + - ``0xb7000000`` + - PWM registers (offset ``0x100`` per channel) + +Debug Support +------------- + +The MCU SoC includes full JTAG debug support via the CV32E40P debug module: + +.. code-block:: python + + debug = OBIDebugModule() + wb_arbiter.add(debug.initiator) + wb_decoder.add(debug.target, name="debug", addr=self.debug_base) + m.d.comb += cpu.debug_req.eq(debug.debug_req) + + m.d.comb += [ + debug.jtag_tck.eq(self.cpu_jtag.tck.i), + debug.jtag_tms.eq(self.cpu_jtag.tms.i), + debug.jtag_tdi.eq(self.cpu_jtag.tdi.i), + debug.jtag_trst.eq(self.cpu_jtag.trst.i), + self.cpu_jtag.tdo.o.eq(debug.jtag_tdo), + ] + +OpenOCD configuration files are provided in ``design/openocd/`` for hardware debugging. + +Custom IP: PWM Controller +------------------------- + +The example includes a custom PWM IP for motor control in ``design/ips/pwm.py``. This demonstrates how to create custom peripherals with their own IO signatures. + +Running the Example +------------------- + +.. code-block:: bash + + cd mcu_soc + pdm chipflow pin lock + pdm sim-check + pdm submit --wait + +Key Differences from Minimal +---------------------------- + +1. **Different CPU**: Uses CV32E40P instead of Minerva, with full debug support +2. **More Peripherals**: Multiple instances of each peripheral type +3. **JTAG Debug**: Full hardware debugging capability +4. **Custom IP**: Includes custom PWM peripheral +5. **Different Target**: IHP SG13G2 process instead of SKY130 + +Customization Ideas +------------------- + +- Adjust peripheral counts to match your requirements +- Add additional custom IP cores +- Modify memory sizes for your application +- Change the target process/package for different fabrication options diff --git a/docs/source/examples/minimal.rst b/docs/source/examples/minimal.rst new file mode 100644 index 0000000..45c68ae --- /dev/null +++ b/docs/source/examples/minimal.rst @@ -0,0 +1,132 @@ +Minimal SoC Example +=================== + +The ``minimal`` example demonstrates the simplest possible ChipFlow SoC design. It includes a RISC-V CPU core with basic peripherals. + +Overview +-------- + +This example creates a System-on-Chip with: + +- **Minerva RISC-V CPU** - A 32-bit RISC-V processor with multiply/divide support +- **QSPI Flash** - External flash memory for code storage +- **SRAM** - 1KB of on-chip RAM +- **GPIO** - 8-bit general purpose I/O +- **GPIO (Open Drain)** - 4-bit open-drain GPIO for I2C-style interfaces +- **UART** - Serial communication at 115200 baud + +Project Structure +----------------- + +.. code-block:: text + + minimal/ + ├── chipflow.toml # Project configuration + ├── design/ + │ ├── design.py # Main SoC design + │ ├── software/ # Firmware source code + │ ├── steps/ # Custom build steps + │ └── tests/ # Test reference data + └── README.md + +Configuration +------------- + +The ``chipflow.toml`` defines the project: + +.. code-block:: toml + + [chipflow] + project_name = "chipflow-examples-minimal" + + [chipflow.top] + soc = "design.design:MySoC" + + [chipflow.steps] + board = "design.steps.board:MyBoardStep" + + [chipflow.silicon] + process = "sky130" + package = "openframe" + + [chipflow.test] + event_reference = "design/tests/events_reference.json" + +Design Overview +--------------- + +The design is defined in ``design/design.py``. Here's the key structure: + +.. code-block:: python + + class MySoC(wiring.Component): + def __init__(self): + super().__init__({ + "flash": Out(QSPIFlashSignature()), + "uart_0": Out(UARTSignature()), + "gpio_0": Out(GPIOSignature(pin_count=8)), + "gpio_open_drain": Out(GPIOSignature( + pin_count=4, + sky130_drive_mode=Sky130DriveMode.OPEN_DRAIN_STRONG_UP + )) + }) + +The component declares its external interfaces using IO Signatures. These signatures tell ChipFlow how to map the design to physical pins. + +Memory Map +---------- + +The SoC uses the following memory map: + +.. list-table:: + :header-rows: 1 + + * - Region + - Base Address + - Description + * - SPI Flash + - ``0x00000000`` + - Code storage (boot address at 1MB offset) + * - SRAM + - ``0x10000000`` + - 1KB on-chip RAM + * - CSR Base + - ``0xb0000000`` + - Control/Status registers + * - GPIO CSR + - ``0xb1000000`` + - GPIO peripheral registers + * - UART CSR + - ``0xb2000000`` + - UART peripheral registers + * - SoC ID CSR + - ``0xb4000000`` + - SoC identification registers + +Running the Example +------------------- + +.. code-block:: bash + + cd minimal + pdm chipflow pin lock + pdm sim-check + pdm submit --wait + +Key Concepts Demonstrated +------------------------- + +1. **IO Signatures**: Using ``QSPIFlashSignature``, ``UARTSignature``, and ``GPIOSignature`` to define peripheral interfaces. + +2. **Wishbone Bus**: Connecting CPU, memory, and peripherals using Wishbone arbiters and decoders. + +3. **CSR Registers**: Using the CSR bus for low-speed peripheral configuration. + +4. **Software Builds**: Attaching firmware to the design with ``SoftwareBuild``. + +Next Steps +---------- + +- Modify the GPIO pin count or add more peripherals +- Change the target process in ``chipflow.toml`` +- Explore the :doc:`mcu-soc` example for a more complete design diff --git a/docs/source/index.rst b/docs/source/index.rst index 478fda7..402a4ae 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,11 +15,23 @@ Contents -------- .. toctree:: - :caption: User Guide + :caption: Getting Started :maxdepth: 2 Chip Configurator chipflow-lib/getting-started + tutorial-intro-chipflow-platform + +.. toctree:: + :caption: Examples + :maxdepth: 2 + + examples/index + +.. toctree:: + :caption: Reference + :maxdepth: 2 + chipflow-lib/index Digital IP Library Amaranth Language and Toolchain From bb333fd142fd8234101a70c18ea5cdb82218e8fc Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 16 Dec 2025 22:27:05 +0000 Subject: [PATCH 2/7] Add CI workflow for documentation review with Claude Code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This adds a GitHub Actions workflow that: - Triggers on PRs and pushes affecting docs/** or *.md files - Builds the documentation to catch build errors - Runs Claude Code to review documentation for: - Technical accuracy (code examples, command-line examples) - Consistency (terminology, code style) - Flow and organization (logical structure) - Completeness (feature coverage, gaps) - Links and references (cross-references, URLs) - Posts review results as PR comments - Uploads review results as artifacts Requires ANTHROPIC_API_KEY secret to be configured in the repository. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .github/docs-review-prompt.md | 78 +++++++++++++ .github/workflows/docs-review.yml | 175 ++++++++++++++++++++++++++++++ 2 files changed, 253 insertions(+) create mode 100644 .github/docs-review-prompt.md create mode 100644 .github/workflows/docs-review.yml diff --git a/.github/docs-review-prompt.md b/.github/docs-review-prompt.md new file mode 100644 index 0000000..a128676 --- /dev/null +++ b/.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. diff --git a/.github/workflows/docs-review.yml b/.github/workflows/docs-review.yml new file mode 100644 index 0000000..3fad9ef --- /dev/null +++ b/.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<> $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 From 4f7e4cced1f6f3b3beaee0fdbe35f4d9693961fd Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 16 Dec 2025 22:45:10 +0000 Subject: [PATCH 3/7] Fix critical and major documentation issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Critical fixes: - Standardize repository naming: example-socs → chipflow-examples - Fix Python version: 3.8 → 3.11+ (matches chipflow-lib requirements) - Update build commands: make → pdm run chipflow (consistent with examples) Major fixes: - Update support channel: Gitter → GitHub Discussions - Fix typo: "reproduable" → "reproducible" - Standardize terminology: "beta" → "alpha program" - Update "Building for Silicon" section to link to examples guide - Fix URLs: build.chipflow.org → build.chipflow.com - Remove broken autoapi/index reference from platform-api.rst 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/source/conf.py | 8 +-- docs/source/examples/getting-started.rst | 4 +- .../tutorial-intro-chipflow-platform.rst | 62 +++++++++---------- 3 files changed, 35 insertions(+), 39 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 1846176..46038e7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -25,15 +25,11 @@ sys.path.append(str(r)) # Fix platform-api.rst to remove autodoc directives (requires chipflow to be installed) -# Replace with overview content that links to autoapi +# Replace with overview content platform_api_content = """Platform API Reference ====================== -This page provides an overview of the ChipFlow platform API. Full API documentation is auto-generated from the source code. - -.. seealso:: - - See the :doc:`autoapi/index` for complete auto-generated API documentation. +This page provides an overview of the ChipFlow platform API. Platforms --------- diff --git a/docs/source/examples/getting-started.rst b/docs/source/examples/getting-started.rst index b0fccba..8314c77 100644 --- a/docs/source/examples/getting-started.rst +++ b/docs/source/examples/getting-started.rst @@ -50,7 +50,7 @@ Set Up Your API Key To submit designs to the ChipFlow cloud builder, you need an API key: -1. Go to https://build.chipflow.org/user/detail +1. Go to https://build.chipflow.com/user/detail 2. Click "Create/Refresh API Key" 3. Copy your new API key (you won't see it again!) @@ -114,7 +114,7 @@ This returns a build URL where you can monitor progress: INFO:chipflow_lib.steps.silicon:Submitting c23dab6-dirty for project chipflow-examples-minimal INFO:chipflow_lib.steps.silicon:Submitted design: {'build_id': '3f51a69c-b3e3-4fd3-88fd-52826ac5e5dd'} - Design submitted successfully! Build URL: https://build.chipflow.org/build/3f51a69c-b3e3-4fd3-88fd-52826ac5e5dd + Design submitted successfully! Build URL: https://build.chipflow.com/build/3f51a69c-b3e3-4fd3-88fd-52826ac5e5dd To stream build logs to your terminal: diff --git a/docs/source/tutorial-intro-chipflow-platform.rst b/docs/source/tutorial-intro-chipflow-platform.rst index f24bf71..221818a 100644 --- a/docs/source/tutorial-intro-chipflow-platform.rst +++ b/docs/source/tutorial-intro-chipflow-platform.rst @@ -38,7 +38,7 @@ Preparing your local environment sudo apt install git pipx -We use `PDM `_ to manage dependencies and ensure reproduable builds of your design. +We use `PDM `_ to manage dependencies and ensure reproducible builds of your design. First install PDM: :: @@ -70,12 +70,12 @@ Getting started First use `Git `_ to get the example sources. :: - git clone https://github.com/ChipFlow/example-socs + git clone https://github.com/ChipFlow/chipflow-examples Then set up your environment: :: - cd example-socs - make init + cd chipflow-examples + pdm install The example project @@ -211,22 +211,22 @@ with: .. code-block:: bash - make sim-build + pdm run chipflow sim build -After running this, we will have a simulation binary at ``build/sim/sim_soc``. +After running this, we will have a simulation binary at ``build/sim/sim_soc``. -We can't run it just yet, as it needs the software/BIOS too. To build the +We can't run it just yet, as it needs the software/BIOS too. To build the software we run: .. code-block:: bash - make software-build + pdm run chipflow software Now that we have our simulation binary, and a BIOS, we can run it: .. code-block:: bash - make sim-run + pdm run chipflow sim run You should see console output like this: @@ -252,23 +252,23 @@ First we need to build the design into a bitstream for the board: .. code-block:: bash - make board-build + pdm run chipflow board build -This will write a file ``build/top.bit``. As for the simulation, we need the -software/BIOS too. +This will write a file ``build/top.bit``. As for the simulation, we need the +software/BIOS too. If we haven't already, build the bios: .. code-block:: bash - make software-build + pdm run chipflow software Now, we load the software/BIOS and design onto board (program its bitstream): .. code-block:: bash - make board-load-software-ulx3s - make board-load-ulx3s + pdm run chipflow board load-software-ulx3s + pdm run chipflow board load-ulx3s Your board should now be running. For us to check that it's working, we can connect to it via its serial port: @@ -460,14 +460,14 @@ We can now take a look at our changes in simulation: .. code-block:: bash - # Rebuild our software - make software-build + # Rebuild our software + pdm run chipflow software # Rebuild our simulation - make sim-build + pdm run chipflow sim build # Run our simulation - make sim-run + pdm run chipflow sim run We should now see the output with button presses: @@ -492,17 +492,17 @@ software and design: .. code-block:: bash - # Rebuild our software - make software-build + # Rebuild our software + pdm run chipflow software # Rebuild our board - make board-build + pdm run chipflow board build # Load software onto board - make board-load-software-ulx3s + pdm run chipflow board load-software-ulx3s # Load design onto board - make board-load-ulx3s + pdm run chipflow board load-ulx3s Now, as in our first example, we need to connect to the board and see its output. @@ -527,11 +527,11 @@ When we press the physical buttons on the board, we should see it: Building for Silicon -------------------- -For this first Alpha, we aren't *quite* ready to start accepting designs on our API. This is coming very soon though! +To submit your design for silicon fabrication, see the :doc:`examples/getting-started` guide which covers the full submission workflow using the ChipFlow API. -`Sign up `_ to be notified when the next Alpha release is available. +`Sign up `_ to be notified when new releases are available. -If you are using this tutorial to test out new designs, reach out to us on `our Gitter channel `_. We would love to add your designs to our test sets! +If you are using this tutorial to test out new designs, reach out to us in our `GitHub Discussions forum `_. We would love to add your designs to our test sets! What's on the roadmap? @@ -544,10 +544,10 @@ We still have a lot of work to do - some things on our roadmap: * Improved simulation tooling. * Many more high-quality Amaranth Peripheral IP modules to include in your designs. -Join the beta -------------- +Join the Alpha Program +---------------------- -If you're interested in the platform, you can `join the beta `_ +If you're interested in the platform, you can `join the alpha program `_ and help us build the future of Python-powered chip design. @@ -556,5 +556,5 @@ Troubleshooting * Python version issues: If you choose to run ``pdm install`` within a venv, PDM will reuse that venv instead of creating a new one. - Ensure that you use a venv with Python 3.8 or greater. + Ensure that you use a venv with Python 3.11 or greater. From 0a9f77b753fa8c684eb28bc6b4503e623b09ef78 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 16 Dec 2025 22:55:39 +0000 Subject: [PATCH 4/7] Fix autoapi configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Disable autoapi_add_toctree_entry to prevent warnings about non-existent chipflow-lib/autoapi/index document - Add post-copy processing to include autoapi-generated indices (chipflow/index and chipflow_lib/index) in the chipflow-lib toctree - This properly integrates the auto-generated API documentation into the navigation while avoiding the toctree reference errors Remaining warnings (18) are from docstring formatting issues in chipflow-lib source code that would need to be fixed upstream. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/source/conf.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 46038e7..abb5226 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -115,6 +115,22 @@ if platform_api_path.exists(): platform_api_path.write_text(platform_api_content) +# Add autoapi toctree to chipflow-lib index +chipflow_lib_index_path = Path('chipflow-lib/index.rst') +if chipflow_lib_index_path.exists(): + content = chipflow_lib_index_path.read_text() + if 'autoapi/chipflow/index' not in content: + # Add API Reference section pointing directly to autoapi-generated indices + content += """ +.. toctree:: + :maxdepth: 2 + :caption: API Reference + + autoapi/chipflow/index + autoapi/chipflow_lib/index +""" + chipflow_lib_index_path.write_text(content) + # -- Project information project = 'ChipFlow' @@ -192,6 +208,7 @@ 'imported-members', ] autoapi_root = "chipflow-lib/autoapi" +autoapi_add_toctree_entry = False # Don't auto-add to toctree (we link manually) # Exclude autoapi templates and in-progress stuff exclude_patterns = [ From 7bd8edf314726f128804e0f35e3b79e98b89b37e Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Wed, 17 Dec 2025 00:05:38 +0000 Subject: [PATCH 5/7] Preserve local changes in vendor repos during docs build MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add check in copy_docs.py to skip git checkout when a vendor repository has uncommitted changes or is on a local branch. This prevents losing work-in-progress changes when rebuilding documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- tools/copy_docs.py | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/tools/copy_docs.py b/tools/copy_docs.py index 903bdc2..01d0afb 100755 --- a/tools/copy_docs.py +++ b/tools/copy_docs.py @@ -10,6 +10,31 @@ from pathlib import Path from typing import List, Tuple + +def has_local_changes(repodir: Path) -> bool: + """Check if a git repository has uncommitted changes or is on a non-detached branch.""" + # Check for uncommitted changes + status_result = subprocess.run( + ['git', '-C', repodir, 'status', '--porcelain'], + capture_output=True, + text=True + ) + if status_result.stdout.strip(): + return True + + # Check if we're on a branch (not detached HEAD) + branch_result = subprocess.run( + ['git', '-C', repodir, 'symbolic-ref', '-q', 'HEAD'], + capture_output=True, + text=True + ) + if branch_result.returncode == 0: + # We're on a branch, check if it has commits ahead of origin + return True + + return False + + def copy_docs(repos: List[Tuple[str, str]]) -> List[Path]: """" Pull in docs from other repos. @@ -43,11 +68,14 @@ def copy_docs(repos: List[Tuple[str, str]]) -> List[Path]: # Check if repo already exists if repodir.exists(): - print(f"{repo_path} already there, updating") - # Git fetch - subprocess.run(['git', '-C', repodir, 'fetch'], check=True) - # Checkout ref - subprocess.run(['git', '-C', repodir, 'checkout', '-f', '--detach', ref], check=True) + if has_local_changes(repodir): + print(f"{repo_path} has local changes, skipping update") + else: + print(f"{repo_path} already there, updating") + # Git fetch + subprocess.run(['git', '-C', repodir, 'fetch'], check=True) + # Checkout ref + subprocess.run(['git', '-C', repodir, 'checkout', '-f', '--detach', ref], check=True) else: print(f"Cloning {repo_path} {ref} as {repodir}") # Clone the repository with gh From 0121d9443c0d77864adab4de0aa69bbdb68c4902 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Wed, 17 Dec 2025 01:09:20 +0000 Subject: [PATCH 6/7] Update docs conf.py for autoapi and fix platform-api.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix import from copy_docs module - Simplify platform-api.rst to use autoapi toctree - Add autoapi_ignore for chipflow_lib backward compat shim - Remove duplicate autoapi_dirs entries - Comment out myst_parser (not installed) - Add print statements for debugging sys.path additions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/source/conf.py | 126 ++++++++------------------------------------ 1 file changed, 21 insertions(+), 105 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index abb5226..5979368 100644 --- a/docs/source/conf.py +++ b/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,114 +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)) -# Fix platform-api.rst to remove autodoc directives (requires chipflow to be installed) -# Replace with overview content -platform_api_content = """Platform API Reference +# Create platform-api.rst in docs/source/ (outside chipflow-lib to avoid copy_docs overwriting) +# Uses autoapi instead of autodoc directives (autodoc requires chipflow to be installed) +# Note: Warning about "nonexisting document" is expected - autoapi generates files after toctree parsing +Path('platform-api.rst').write_text("""Platform API Reference ====================== -This page provides an overview of the ChipFlow platform API. +This section provides the API reference for the ChipFlow platform library. -Platforms ---------- - -The ChipFlow library provides several platform implementations for different build targets: - -**SimPlatform** (``chipflow.platform.sim``) - Platform for building and running CXXRTL simulations. Use this during development to test your design. - -**SiliconPlatform** (``chipflow.platform.silicon``) - Platform for targeting ASIC fabrication. Supports various foundry processes including SKY130, GF180, GF130BCD, and IHP_SG13G2. - -**SoftwarePlatform** (``chipflow.platform.software``) - Platform for building RISC-V software to run on your design. - -Build Steps ------------ - -Steps are the building blocks of the ChipFlow build system: - -**SimStep** (``chipflow.platform.sim_step``) - Handles simulation workflow: building the simulator, running simulations, and checking results. - -**SiliconStep** (``chipflow.platform.silicon_step``) - Handles ASIC preparation: elaborating designs to RTLIL and submitting to the ChipFlow cloud builder. - -**SoftwareStep** (``chipflow.platform.software_step``) - Handles RISC-V software compilation. - -**BoardStep** (``chipflow.platform.board_step``) - Handles board-level operations. - -IO Signatures -------------- - -IO Signatures define standard interfaces for your design. They provide a consistent way to connect peripherals and specify electrical characteristics. - -Base Signatures -~~~~~~~~~~~~~~~ - -- **IOSignature** - Base class for all IO signatures -- **OutputIOSignature** - For output-only signals -- **InputIOSignature** - For input-only signals -- **BidirIOSignature** - For bidirectional signals - -Protocol Signatures -~~~~~~~~~~~~~~~~~~~ - -Pre-defined signatures for common protocols: - -- **UARTSignature** - UART serial interface -- **GPIOSignature** - General purpose I/O -- **SPISignature** - SPI bus interface -- **I2CSignature** - I2C bus interface -- **QSPIFlashSignature** - Quad SPI flash interface -- **JTAGSignature** - JTAG debug interface - -IO Configuration ----------------- - -**IOModel** - Configures electrical characteristics of IO pads (drive mode, trip point, inversion). - -**IOModelOptions** - Available options for IO configuration. - -**IOTripPoint** - Voltage threshold configuration for input signals. - -Utility Functions ------------------ - -**setup_amaranth_tools()** - Sets up the Amaranth toolchain for your environment. - -**top_components()** - Returns dictionary of instantiated top-level components from configuration. - -**get_software_builds()** - Returns software build configurations from the design. -""" -platform_api_path = Path('chipflow-lib/platform-api.rst') -if platform_api_path.exists(): - platform_api_path.write_text(platform_api_content) - -# Add autoapi toctree to chipflow-lib index -chipflow_lib_index_path = Path('chipflow-lib/index.rst') -if chipflow_lib_index_path.exists(): - content = chipflow_lib_index_path.read_text() - if 'autoapi/chipflow/index' not in content: - # Add API Reference section pointing directly to autoapi-generated indices - content += """ .. toctree:: - :maxdepth: 2 - :caption: API Reference + :maxdepth: 3 - autoapi/chipflow/index - autoapi/chipflow_lib/index -""" - chipflow_lib_index_path.write_text(content) + /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 @@ -148,7 +63,7 @@ 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx_copybutton', - 'myst_parser', + # 'myst_parser', 'sphinx.ext.todo', 'sphinx.ext.napoleon', 'sphinx.ext.autodoc', @@ -193,8 +108,6 @@ autodoc_typehints = 'description' autoapi_dirs = [ - top_path / "vendor/chipflow-lib/chipflow_lib/platforms", - top_path / "vendor/chipflow-lib/chipflow_lib", top_path / "vendor/chipflow-lib/chipflow", ] autoapi_generate_api_docs = True @@ -209,6 +122,9 @@ ] autoapi_root = "chipflow-lib/autoapi" autoapi_add_toctree_entry = False # Don't auto-add to toctree (we link manually) +autoapi_ignore = [ + "*/chipflow_lib/*", # Backward compatibility shim +] # Exclude autoapi templates and in-progress stuff exclude_patterns = [ From dab75eccb1bf6f8d88e94a2632d0533f87362100 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Wed, 17 Dec 2025 01:52:20 +0000 Subject: [PATCH 7/7] Fix platform-api.rst toctree to correctly link autoapi docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Use relative path for toctree entry to chipflow-lib/autoapi/chipflow/index - Exclude chipflow-lib/platform-api.rst since we use root level platform-api.rst - Updated comments for clarity 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/source/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 5979368..1c0670b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -26,8 +26,7 @@ sys.path.append(str(r)) # Create platform-api.rst in docs/source/ (outside chipflow-lib to avoid copy_docs overwriting) -# Uses autoapi instead of autodoc directives (autodoc requires chipflow to be installed) -# Note: Warning about "nonexisting document" is expected - autoapi generates files after toctree parsing +# This file points to the autoapi-generated index Path('platform-api.rst').write_text("""Platform API Reference ====================== @@ -36,7 +35,7 @@ .. toctree:: :maxdepth: 3 - /chipflow-lib/autoapi/chipflow/index + chipflow-lib/autoapi/chipflow/index """) # Update chipflow-lib/index.rst to point to the platform-api.rst outside chipflow-lib/ @@ -121,7 +120,7 @@ 'imported-members', ] autoapi_root = "chipflow-lib/autoapi" -autoapi_add_toctree_entry = False # Don't auto-add to toctree (we link manually) +autoapi_add_toctree_entry = False # We'll manually add to toctree in platform-api.rst autoapi_ignore = [ "*/chipflow_lib/*", # Backward compatibility shim ] @@ -131,6 +130,7 @@ 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", ]