py-shiny-site: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

This is the Shiny for Python documentation website - the official documentation, API reference, component gallery, and template showcase for the Shiny for Python framework. Built with Quarto, it combines hand-written conceptual documentation with auto-generated API reference docs extracted from the main py-shiny repository.

Commits and Pull Requests

Use Conventional Commits for both commit messages and PR titles. Format: <type>: <description> (or <type>(<scope>): <description>).

Common types in this repo: feat, fix, docs, ci, test, refactor, chore, build. Examples:

• docs: add Accordion layout component page
• ci: verify shinylive links are up to date
• fix: point install-quarto at renamed site.yml workflow

Development Commands

Initial Setup

# Clone and initialize submodules
git clone https://github.com/posit-dev/py-shiny-site.git
cd py-shiny-site
make submodules

# Full build (creates venv, installs deps, generates API docs, builds site)
make all

Or, for any fresh checkout or git worktree, one command does submodules + deps

• generated docs and seeds _build//render caches from a sibling checkout:

make ai-setup

(Conductor workspaces run this automatically via .conductor/settings.toml.)

Common Development Workflow

# One-command init for a fresh checkout/worktree (submodules, deps, generated
# docs; seeds _build/ and render caches from a sibling checkout when possible)
make ai-setup

# Serve with live preview. Runs a parallel full build first ONLY if _build/ is
# missing or older than _quarto.yml; otherwise starts instantly and re-renders
# just the pages you edit.
make serve

# Serve with a full SERIAL initial render (~35 min). Use after changing
# _quarto.yml, the SCSS theme, includes, or extensions — `make serve` skips
# the up-front full render, so site-wide config changes won't propagate there.
make serve-serial

# Full site build using local parallel shards (~9 min on a multi-core machine)
make site-parallel

# Full serial site build (the fidelity reference; what CI shards run internally)
make site

# Rebuild API documentation from py-shiny submodule
# (skips itself when the submodule commit, _renderer.py, quartodoc configs,
# and requirements.txt are unchanged — stamp file: .quartodoc-stamp)
make quartodoc

# Rebuild component previews and Shinylive links
make docs

# Clean build artifacts (also purges .quarto/shinylive-cache)
make clean

# Pull latest changes including submodules
git pull
make submodules
make all