.. _configuration: ************* Configuration ************* ``scaldys-project`` reads project-specific build settings from a ``scaldys-project.toml`` file in the project root. Every setting has a default, so the file is entirely optional — pure-Python projects with packaging files in the default location require no configuration at all. File location ============= Place ``scaldys-project.toml`` alongside ``pyproject.toml`` in your project root:: my-project/ pyproject.toml scaldys-project.toml ← optional src/ packaging/windows/ Sections ======== ``[cython]`` ------------ Controls Cython compilation. .. code-block:: toml [cython] compiled_modules = [ "myapp.core.engine", "myapp.core.crypto", ] source_root = "src" .. list-table:: :header-rows: 1 :widths: 25 15 60 * - Key - Default - Description * - ``compiled_modules`` - ``[]`` - List of fully-qualified dotted module paths to compile with Cython. An empty list (the default) disables Cython; source files are staged as-is for PyInstaller. **Note: Compiled modules must not use match/case (PEP 634) syntax.** * - ``source_root`` - ``"src"`` - Directory relative to the project root that contains your Python source packages. For a ``src``-layout project this is ``"src"``; for a flat layout it is typically ``"."`` or the package name itself. **Example — no Cython compilation** (pure-Python project) .. code-block:: toml # [cython] section omitted — defaults apply **Example — compile selected modules** .. code-block:: toml [cython] compiled_modules = [ "myapp.core.engine", # performance-critical inner loop "myapp.core.crypto", # obfuscation: hide algorithm details ] See :ref:`cython_compilation` for a full explanation of how compilation works. ``[docs]`` ---------- Controls which documentation units are distributed to end users. .. code-block:: toml [docs] public_doc_dirs = ["manual"] .. list-table:: :header-rows: 1 :widths: 25 15 60 * - Key - Default - Description * - ``public_doc_dirs`` - ``[]`` - List of subdirectory names under ``docs/`` whose built HTML output (``build//html/``) is copied into the distribution artefacts: ``dist/portable/documentation//`` (alongside the portable package) and ``dist/documentation//`` (standalone documentation copy). These are the documentation units destined for end users of the program. An empty list means no documentation is distributed. **Example — distribute one unit to end users** .. code-block:: toml [docs] public_doc_dirs = ["manual"] See :ref:`documentation_building` for a full explanation of how the doc build works. ``[windows]`` ------------- Controls Windows-specific packaging paths, the deployment strategy, and distribution options. .. code-block:: toml [windows] script_dir = "packaging/windows" deployment_mode = "pyinstaller" bundle_pyruntime = false .. list-table:: :header-rows: 1 :widths: 25 25 50 * - Key - Default - Description * - ``script_dir`` - ``"packaging/windows"`` - Directory relative to the project root containing the Windows packaging files: Inno Setup script (``.iss``), launcher scripts (``.bat``, ``.ps1``), and the optional application icon (``.ico``). * - ``deployment_mode`` - ``"wheel_only"`` - Controls how the application is packaged for Windows users. Three values are supported: ``"wheel_only"`` (default) Builds a binary distribution wheel only. No Windows installer is created. Use this for packages distributed via ``pip`` or ``uv`` rather than a setup ``.exe``. The Inno Setup script and launcher files are not required. ``"pyinstaller"`` PyInstaller bundles your application into a self-contained executable directory. Inno Setup wraps it into a setup ``.exe``. No Python installation is required on the end-user's machine. ``"pyruntime"`` PyInstaller is *not* used. The installer deploys a managed Python virtual environment (``PythonRuntime``) into the installation directory. The launcher scripts activate that environment. Use this mode when the application must coexist with tools such as Quarto or Jupyter that require a real Python interpreter. Requires ``.python-version`` at the project root. See :ref:`windows_exe` for a full description of each mode. * - ``bundle_pyruntime`` - ``false`` - *Only meaningful when* ``deployment_mode = "pyruntime"``. When ``true``, pre-builds a PythonRuntime virtual environment at ``dist/pyruntime/`` and passes its path to Inno Setup as ``/DPythonRuntimeDir``, enabling an offline installer that requires no internet access on the end-user's machine. Requires ``.python-version`` at the project root and ``uv`` on ``PATH``. See :ref:`windows_installer` — *Online and offline installer modes*. See :ref:`windows_installer` for details on what each packaging file should contain. ``[format]`` ------------ Controls target files and directories for Markdown and code formatting. .. code-block:: toml [format] markdown_targets = ["README.md", "docs/site"] .. list-table:: :header-rows: 1 :widths: 25 15 60 * - Key - Default - Description * - ``markdown_targets`` - ``None`` (unconfigured) - List of files and directories (relative to project root) to format with ``mdformat``. Specified files are formatted directly; directories are scanned recursively for ``*.md`` files. When omitted or ``None``, automatic discovery applies (``README.md`` and all MkDocs documentation directories under ``docs/``). When set to an explicit empty list (``[]``), no Markdown files are formatted. **Example — customize formatting targets** .. code-block:: toml [format] markdown_targets = ["README.md", "docs/user_guide"] See :ref:`markdown_formatting_guide` for details on Markdown formatting and CI checks. Complete example ================ .. code-block:: toml [cython] compiled_modules = [ "myapp.core.engine", "myapp.core.crypto", ] source_root = "src" [windows] script_dir = "packaging/windows" deployment_mode = "pyinstaller" [docs] public_doc_dirs = ["manual"] [format] markdown_targets = ["README.md", "docs/manual"] Annotated reference file ======================== For a single copy-paste-ready block that lists every option with inline comments, see :ref:`scaldys_project_toml_reference`. Defaults summary ================ If ``scaldys-project.toml`` is absent, or a section / key is missing, the following defaults apply: .. list-table:: :header-rows: 1 :widths: 35 65 * - Setting - Default value * - ``cython.compiled_modules`` - ``[]`` (Cython disabled) * - ``cython.source_root`` - ``"src"`` * - ``windows.script_dir`` - ``"packaging/windows"`` * - ``windows.deployment_mode`` - ``"pyinstaller"`` * - ``windows.bundle_pyruntime`` - ``false`` (online installer; only applies in ``pyruntime`` mode) * - ``docs.public_doc_dirs`` - ``[]`` (no documentation distributed) * - ``format.markdown_targets`` - ``None`` (auto-discovery: ``README.md`` + MkDocs docs)