Quick Start

This guide covers two paths:

  • Starting a new project — use scaldys-project init to scaffold a complete project from scaldys-template in one step.

  • Adding to an existing project — manually wire up the required files and configuration for a Python project that already exists.

Starting a new project

The fastest way to begin is scaldys-project init. It downloads scaldys-template, asks a short set of questions, and produces a fully configured project directory with a working virtual environment.

Run it from the directory where you want the new project to appear (for example, your workspace root):

scaldys-project init

The wizard walks you through four sections:

  1. Project identity — project name, package name, slug, organisation.

  2. Author & metadata — name, email, description, version.

  3. Build configuration — Windows deployment mode.

  4. Output — target directory (default: ./<project-slug>), whether to initialise git, whether to run uv sync.

After confirming the summary, the command creates the project, optionally initialises a git repository, and runs uv sync to install dependencies.

Then move into the project and verify it:

cd my-cool-app
uv run scaldys-project check

For the full details of every wizard prompt, substitution step, and CLI flag see Project Initialisation.

Adding to an existing project

This guide walks you through setting up an existing Python project to use scaldys-project and running your first complete Windows build.

It assumes scaldys-project is already installed in your project — if not, see Installation first.

Prerequisites (existing project)

  • scaldys-project installed as a dev dependency (see Installation)

  • A Python project with a pyproject.toml at its root

  • Windows (required for the build steps)

  • Inno Setup installed (pyinstaller and pyruntime modes only) — download from jrsoftware.org and install to the default location

Step 1 — Create scaldys-project.toml

For a pure-Python project with packaging files in the default location (packaging/windows/), no configuration file is needed — skip to Step 2.

For anything else, create scaldys-project.toml in your project root:

[cython]
compiled_modules = [
    "myapp.core.engine",
    "myapp.core.crypto",
]

[windows]
script_dir = "packaging/windows"
deployment_mode = "pyinstaller"   # or "pyruntime" or "wheel_only"

See Configuration for the full configuration reference.

Step 2 — Add Windows packaging files

Create the directory specified by [windows] script_dir (default: packaging/windows/) and place the following project-specific files inside it:

packaging/windows/
    myapp.iss               # Inno Setup script
    myapp_commandline.bat   # Command-line launcher
    myapp_powershell.ps1    # PowerShell launcher
    myapp.ico               # Application icon (optional)

Replace myapp with your project name as declared in pyproject.toml.

In wheel_only mode these files are not required.

See Windows Installer Creation for the expected content of each file, including a minimal myapp.iss template and auto-detecting launcher script examples.

Step 3 — Prepare your Sphinx documentation

Create a subdirectory under docs/ for each documentation unit. The name is freely choosable — manual, help, guide, or anything else. scaldys-project detects the engine automatically: a directory containing source/conf.py is treated as a Sphinx project.

If you do not already have a Sphinx project, create one from your project root (replace manual with your chosen name):

sphinx-quickstart docs/manual

When prompted, choose yes to separate source and build directories. This produces the docs/manual/source/ layout that Sphinx requires.

To declare which documentation units should be bundled into the installer, add to scaldys-project.toml:

[docs]
public_doc_dirs = ["manual"]

See Documentation Building for the complete expected layout, engine auto-detection rules, and Sphinx configuration tips.

Step 4 — Run the full build

From anywhere inside your project tree, run:

scaldys-project build all

scaldys-project walks up the directory tree to find pyproject.toml automatically — you do not need to cd to the project root first.

The command runs the following stages in order:

  1. docs — Builds the Sphinx documentation

  2. Cython compilation (if configured) — compiles selected modules to .pyd

  3. Windows distribution — mode-dependent (PyInstaller or wheel build)

  4. installer (pyinstaller and pyruntime modes) — runs Inno Setup

A Rich progress bar tracks each stage. Output artefacts land in:

build/                ← intermediate artefacts
dist/
    myapp-1.2.3-...whl    ← distribution wheel
artifacts/
    portable/             ← staged distribution tree (pyinstaller/pyruntime modes)
    installer/            ← generated Windows installer (pyinstaller/pyruntime modes)
    documentation/        ← standalone docs copy (if public_doc_dirs is set)

Step 5 — Run individual stages

You can run each stage independently:

# Build documentation only
scaldys-project build docs

# Build Windows distribution only (mode-dependent, no docs rebuild)
scaldys-project build windows

# Remove build/, dist/ and artifacts/ directories
scaldys-project build clean

All commands accept --verbose / -v for detailed debug output:

scaldys-project build all --verbose

For ci, format, and test commands, the core subprocess command syntax is already displayed at the standard INFO level (in dim text) without requiring the verbose flag.

Next steps