CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Sphinx-based documentation project for wafer.space end user documentation. The documentation uses:

  • Sphinx as the documentation generator

  • Furo theme for styling

  • MyST Parser for Markdown support

  • Cogapp for code generation

Common Commands

Build Documentation

# Build HTML documentation
make html

# Clean build directory and rebuild
make clean html

# Build other formats
make latexpdf  # PDF via LaTeX
make epub      # EPUB format

Development Server

# Live reload server for development
make livehtml
# OR
sphinx-autobuild -b html . _build

Install Dependencies

# Setup virtual environment and install dependencies
make setup

# Or just install dependencies in current environment
make install

# Clean virtual environment
make clean-venv

Architecture Notes

Documentation Structure

  • Main entry point: index.md - Contains the master table of contents

  • Configuration: conf.py - Sphinx configuration with project metadata and extension settings

  • Build output: _build/ directory (gitignored)

  • Templates: _templates/base.html for custom HTML modifications

Key Configuration Details

  • Uses MyST parser with colon_fence extension enabled for enhanced Markdown features

  • Git-based versioning automatically extracted from tags

  • Source files use .rst suffix by default but .md files are supported via MyST

  • Theme: Furo (modern, responsive documentation theme)

Adding New Pages

  1. Create new .md files in the root directory

  2. Add the filename (without extension) to the toctree in index.md

  3. The documentation will automatically include the new page in the build

Important Build Behavior

  • The build process uses git describe --tags --always to determine version numbers

  • All Markdown files support MyST syntax including directives and roles

  • The project name “wafer.space End User Documentation” is used throughout the build

Git Workflow

Branch Management

  • When making changes, start a new git branch and then make sure to commit to the git repository frequently as you work

  • Once the work has been completed ask the user if you should merge the created branch into the main branch

  • Don’t delete the branches after merging

  • When merging the branches to main, make sure to not fast forward