CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.Development Commands
Local Development
- Install Mintlify CLI globally:
npm i -g mintlify
- Start local development server:
mintlify dev
- Install dependencies if dev server fails:
mintlify install
Spell Checking
- Install cspell:
npm -g install cspell
- Check spelling in all MDX files:
npx cspell **/*.mdx
- Add new technical terms to
/project-words.txt
API Documentation Generation
- Generate API docs from OpenAPI spec:
npx @mintlify/scraping@latest openapi-file api-reference/spec.yaml -o api-reference
Repository Architecture
Content Structure
This is a documentation repository for IonQ’s Quantum Cloud platform built with Mintlify. The site structure is:- API Reference (
/api-reference/
): Auto-generated from OpenAPI specs inspec.yaml
files- v0.3 and v0.4 API versions with separate specs
- Additional manual
.mdx
files for navigation and custom content
- Guides (
/guides/
): Step-by-step tutorials for specific tasks - User Manual (
/user-manual/
): Reference documentation for platform features - SDKs (
/sdks/
): Documentation for various quantum computing SDKs (Qiskit, Cirq, PennyLane, qBraid, etc.) - Partners (
/partners/
): Integration guides for cloud partners (AWS Braket, Azure Quantum, etc.) - Snippets (
/snippets/
): Reusable content blocks
Key Configuration Files
mint.json
: Mintlify configuration defining navigation, theming, and site structurecspell.json
: Spell checker configurationproject-words.txt
: Custom dictionary for technical terms- OpenAPI specs:
/api-reference/v0.3/spec.yaml
/api-reference/v0.4/spec-backends.yaml
/api-reference/v0.4/spec-api-users.yaml
Content Types
- API Reference: Generated from OpenAPI specs, with
.mdx
files as navigation pointers - Guides: Focus on single, specific actions with step-by-step instructions
- User Manual: Concise reference organized around core platform objects (Accounts, Backends, Jobs, Organizations, Projects)
Style Guidelines
- Use lowercase in titles: “Resetting your password” not “Resetting Your Password”
- Prefer small, short sections with linkable headers
- Always use
IONQ_API_KEY
as the environment variable name in examples - Content is written in MDX format (Markdown with JSX components)
Navigation Management
- All page navigation is defined in
mint.json
- Pages can be viewed locally before being added to navigation by accessing their URL directly
- Use the
redirects
section inmint.json
for URL changes
Content Guidelines
- Target audience: Quantum software developers using Python, Qiskit, Windows/Mac desktop users
- Focus on practical, actionable content
- Screenshots and media stored in
_media/
subdirectories - Use project-specific terminology found in
project-words.txt
- Local test environments can be run using the
mint
CLI tool, which can be installed withnpm i -g mint
if needed. - This project uses Mintlify to build and deploy the site. It’s documentation can be found at https://mintlify.com/docs
- When working on pages with API examples, try testing those examples using a local key if one is available. This can be accessed through a Bash environment variable in $IONQ_API_KEY