Overview

What scaldys-project does for you

You write Python. scaldys-project takes care of turning that code into something you can hand to a Windows user.

Running a single command from your project root:

scaldys-project build all

produces, in order:

  1. HTML documentation — every documentation unit under docs/ built to HTML, with configured units bundled into the installer for offline use.

  2. A Windows distribution — the exact form depends on the deployment_mode you choose in scaldys-project.toml:

    • wheel_only (default): only a binary distribution wheel is produced. Use this for packages distributed via pip or uv.

    • pyinstaller: PyInstaller bundles the application into a self-contained directory that runs on any Windows machine without a Python installation.

    • pyruntime: a managed Python virtual environment is deployed alongside the application. Use this when your app must coexist with Quarto, Jupyter, or another tool that requires a real Python interpreter.

    In all modes, a .pyd-only distribution wheel is built from compiled sources. Optionally, selected modules are first compiled to native .pyd extensions with Cython for performance or to avoid shipping plain source code.

  3. A Windows installer (pyinstaller and pyruntime modes) — an Inno Setup .exe that installs the application, the documentation, launcher scripts, and example files; adds Start Menu and Desktop shortcuts; and handles uninstallation cleanly.

The end result is an artifacts/installer/ folder containing a single setup.exe that you can ship directly to users, and a dist/ folder with the distribution wheel.

The build pipeline at a glance

Your project
     │
     ▼
┌─────────────┐     Sphinx        ┌──────────────────────────┐
│  docs/      │ ────────────────▶│ build/<name>/html/       │
│  manual/    │                   └──────────────┬───────────┘
│  dev_guide/ │                                  │
└─────────────┘                                  │ public_doc_dirs → installer
┌─────────────┐   Cython (opt.)  ┌─────────────────────────────┐
│  src/       │ ───────────────▶│ build/compiled/             │
│  myapp/     │                  └───────────────┬─────────────┘
└─────────────┘                                  │
                                                 │ Mode 1: PyInstaller
                                                 │ Mode 2: wheel + uv venv
                                                 │ Mode 3: wheel only
                                                 ▼
                                   ┌──────────────────────────────┐
                                   │ dist/                        │
                                   │   myapp-1.2.3-...win_amd64.whl │
                                   └──────────────────────────────┘
                                   ┌──────────────────────────────┐
                                   │ artifacts/portable/ (Mode 1&2)│
                                   │   bin/  ...  documentation/  │
                                   └──────────────┬───────────────┘
┌──────────────────┐  Inno Setup  (Mode 1 & 2)   │
│ packaging/       │ ────────────────────────────▶
│ windows/         │
│   myapp.iss      │               ┌────────────────────────────┐
└──────────────────┘               │ artifacts/installer/       │
                                   │   setup.exe                │
                                   └────────────────────────────┘

Getting started quickly with scaldys-template

Setting up all the required files (Sphinx project, Inno Setup script, launcher scripts, scaldys-project.toml, pyproject.toml, GitHub Actions workflows, …) from scratch takes time. scaldys-template is a ready-to-use project template that already has everything wired together:

  • A src-layout Python package with a Typer-based CLI entry point

  • scaldys-project.toml pre-configured with an example Cython module and deployment_mode = "pyinstaller"

  • packaging/windows/ with a complete .iss script, auto-detecting launcher scripts, and an application icon

  • docs/manual/ with a working Sphinx project (freely renameable)

  • pyproject.toml declaring scaldys-project[cython,windows,docs] as a dev dependency

  • GitHub Actions workflows for CI, PyPI publishing, and release management

Use scaldys-project init to scaffold a new project from the template in one step — the interactive wizard downloads the template, substitutes all placeholder names, and optionally runs git init and uv sync:

scaldys-project init

For a detailed walkthrough of every wizard prompt and option, see Project Initialisation.

Where to go next

Starting a new project from scratch?

Run scaldys-project init — it downloads scaldys-template and scaffolds a fully configured project directory from an interactive wizard. See Project Initialisation or jump straight to Quick Start.

Adding ``scaldys-project`` to an existing project?

Start with Installation to add it as a dev dependency, then follow the Quick Start to set up the required files and run your first build.

Already set up and looking for reference information?