From 7d285d161fd72b9968b5b5fa1a0a8acf2496c8fd Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Thu, 16 Oct 2025 16:25:20 +0200 Subject: [PATCH 01/18] 1st commit for introducing `pixi` Add pixi manifest file and git-related files which are automatically generated by `pixi` --- .gitattributes | 2 + .gitignore | 9 ++- pixi.toml | 153 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 163 insertions(+), 1 deletion(-) create mode 100644 .gitattributes create mode 100644 pixi.toml diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..887a2c18 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# SCM syntax highlighting & preventing 3-way merges +pixi.lock merge=binary linguist-language=YAML linguist-generated=true diff --git a/.gitignore b/.gitignore index 7045bc61..ea448d57 100644 --- a/.gitignore +++ b/.gitignore @@ -21,4 +21,11 @@ build/ .nfs* .coverage htmlcov* -cherab.egg-info/ \ No newline at end of file +cherab.egg-info/ + +# pixi environments +.pixi/* +!.pixi/config.toml + +# Ignore lock files until we start using them +pixi.lock diff --git a/pixi.toml b/pixi.toml new file mode 100644 index 00000000..f75a8e15 --- /dev/null +++ b/pixi.toml @@ -0,0 +1,153 @@ +[workspace] +channels = ["https://prefix.dev/conda-forge"] +platforms = ["linux-64", "osx-arm64", "osx-64"] +preview = ["pixi-build"] + +# ------------------------------- +# === Packaging Configuration === +# ------------------------------- +[package] +name = "cherab" +version = "dynamic" + +[package.build] +backend = { name = "pixi-build-python", version = "*" } + +[package.build.config] +noarch = false +compilers = ["c"] + +[workspace.build-variants] +python = ["3.9", "3.10.*", "3.11.*", "3.12.*", "3.13.*"] + +[package.host-dependencies] +uv = "*" +python = "*" +setuptools = "*" +cython = ">=3.1" +numpy = "*" +raysect = "0.9.*" + +[package.run-dependencies] +scipy = "*" +matplotlib-base = "*" +pyopencl = "*" +pocl = "*" + +# --------------------------------- +# === Development Configuration === +# --------------------------------- +[dependencies] +ipython = "*" + +[tasks] +clean = { cmd = [ + "find", + "cherab/", + "-type", + "f", + "\\(", + "-name", + "'*.c'", + "-o", + "-name", + "'*.so'", + "-o", + "-name", + "'*.dylib'", + "\\)", + "-delete", +], description = "๐Ÿ”ฅ Remove in-place build artifacts and temporary files (*.c, *.so, *.dylib)" } + +# The documentation-related tasks below do not require the source package. +doc-clean = { cmd = [ + "rm", + "-rf", + "build", +], cwd = "docs", description = "๐Ÿ”ฅ Clean the docs build directory" } +doc-serve = { cmd = [ + "python", + "-m", + "http.server", + "8000", + "--directory", + "build/html", +], cwd = "docs", description = "๐Ÿš€ Start a local server for the docs" } + +# === Testing feature === +[feature.test.dependencies] +cherab = { path = "." } + +[feature.test.tasks] +test = { cmd = "python -m unittest discover cherab -v", description = "๐Ÿงช Run the tests" } + +# === Documentation feature === +[feature.docs.dependencies] +cherab = { path = "." } +sphinx = "*" +sphinx_rtd_theme = "<1" + +[feature.docs.pypi-dependencies] +sphinx-tabs = "*" # >=3.4.4 has not yet been released to conda-forge + +[feature.docs.tasks] +doc-build = { cmd = [ + "sphinx-build", + "-b", + "{{ target }}", + "source", + "build/{{ target }}", +], cwd = "docs", args = [ + { arg = "target", default = "html" }, +], description = "๐Ÿ“ Build the docs" } + +# === Linting feature === +[feature.lint.dependencies] +dprint = "*" +lefthook = "*" +ruff = "*" +typos = "*" +actionlint = "*" +shellcheck = "*" +validate-pyproject = "*" +cython-lint = "*" +blacken-docs = "*" +taplo = "*" + +[feature.lint.tasks] +lefthook = { cmd = "lefthook", description = "๐Ÿ”— Run lefthook" } +hooks = { cmd = "lefthook install", description = "๐Ÿ”— Install pre-commit hooks" } +pre-commit = { cmd = "lefthook run pre-commit", description = "๐Ÿ”— Run pre-commit checks" } +ruff-check = { cmd = "ruff check", description = "Lint with ruff" } +ruff-format = { cmd = "ruff format", description = "Format with ruff" } +dprint = { cmd = "dprint fmt", description = "Format with dprint" } +typos = { cmd = "typos --write-changes --force-exclude", description = "Fix typos" } +taplo = { cmd = "taplo fmt", description = "Format toml files with taplo" } +actionlint = { cmd = "actionlint", description = "Lint actions with actionlint" } +blacken-docs = { cmd = "blacken-docs", description = "Format Python markdown blocks with Black" } +validate-pyproject = { cmd = "validate-pyproject pyproject.toml", description = "Validate pyproject.toml" } +cython-lint = { cmd = "cython-lint", description = "Lint Cython files" } +lint = { cmd = "lefthook run pre-commit --all-files --force", description = "๐Ÿงน Run all linters" } + +# === Python Version Features === +[feature.py39.dependencies] +python = "3.9.*" +[feature.py313.dependencies] +python = "3.13.*" + +[environments] +default = { features = ["py313"], solve-group = "py313" } +test = { features = ["test"], solve-group = "py313" } +docs = { features = [ + "py39", + "docs", +], solve-group = "py39" } # TODO: change to py313 when bumping RTD theme to >=1.0 +test-py313 = { features = [ + "py313", + "test", +], solve-group = "py313" } # alias of tests +test-py39 = { features = [ + "py39", + "test", +], solve-group = "py39" } # alias of tests +lint = { features = ["lint"], no-default-feature = true } From f2ee0d3754eb87477255b3ffef01dc37bcc17556 Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Fri, 28 Nov 2025 14:40:33 +0100 Subject: [PATCH 02/18] Update raysect dependency version to 0.9.1.* --- pixi.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pixi.toml b/pixi.toml index f75a8e15..6ff8ae88 100644 --- a/pixi.toml +++ b/pixi.toml @@ -26,7 +26,7 @@ python = "*" setuptools = "*" cython = ">=3.1" numpy = "*" -raysect = "0.9.*" +raysect = "0.9.1.*" [package.run-dependencies] scipy = "*" From 6f9dddd37d3eb0391a356a245ec8a1abef524314 Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Fri, 28 Nov 2025 14:50:20 +0100 Subject: [PATCH 03/18] Revert "Update raysect dependency version to 0.9.1.*" This reverts commit f2ee0d3754eb87477255b3ffef01dc37bcc17556. --- pixi.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pixi.toml b/pixi.toml index 6ff8ae88..f75a8e15 100644 --- a/pixi.toml +++ b/pixi.toml @@ -26,7 +26,7 @@ python = "*" setuptools = "*" cython = ">=3.1" numpy = "*" -raysect = "0.9.1.*" +raysect = "0.9.*" [package.run-dependencies] scipy = "*" From c145a4d1776d87fd93e2545a57d69446ec041430 Mon Sep 17 00:00:00 2001 From: Koyo MUNECHIKA <51052381+munechika-koyo@users.noreply.github.com> Date: Wed, 15 Jul 2026 16:45:32 +0900 Subject: [PATCH 04/18] Update Python version range in pixi.toml --- pixi.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pixi.toml b/pixi.toml index f75a8e15..c6d78fb8 100644 --- a/pixi.toml +++ b/pixi.toml @@ -18,7 +18,7 @@ noarch = false compilers = ["c"] [workspace.build-variants] -python = ["3.9", "3.10.*", "3.11.*", "3.12.*", "3.13.*"] +python = ["3.9.*", "3.10.*", "3.11.*", "3.12.*", "3.13.*", "3.14.*"] [package.host-dependencies] uv = "*" From 8c8a189047bd9c51c72a58f9212c92cf3d028a98 Mon Sep 17 00:00:00 2001 From: Koyo MUNECHIKA <51052381+munechika-koyo@users.noreply.github.com> Date: Wed, 15 Jul 2026 16:47:17 +0900 Subject: [PATCH 05/18] Add HTML file removal to build artifacts cleanup Added support for removing HTML build artifacts. --- pixi.toml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pixi.toml b/pixi.toml index c6d78fb8..1a5d3f9e 100644 --- a/pixi.toml +++ b/pixi.toml @@ -55,6 +55,9 @@ clean = { cmd = [ "-o", "-name", "'*.dylib'", + "-o", + "-name", + "'*.html'", "\\)", "-delete", ], description = "๐Ÿ”ฅ Remove in-place build artifacts and temporary files (*.c, *.so, *.dylib)" } From 053cf8c37e98bb2de562c458d3aac7680339fc26 Mon Sep 17 00:00:00 2001 From: Koyo MUNECHIKA <51052381+munechika-koyo@users.noreply.github.com> Date: Wed, 15 Jul 2026 16:53:00 +0900 Subject: [PATCH 06/18] Update Python version features in pixi.toml Renaming python-featured environments to avoid specific Python versions --- pixi.toml | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/pixi.toml b/pixi.toml index 1a5d3f9e..d913d686 100644 --- a/pixi.toml +++ b/pixi.toml @@ -133,24 +133,24 @@ cython-lint = { cmd = "cython-lint", description = "Lint Cython files" } lint = { cmd = "lefthook run pre-commit --all-files --force", description = "๐Ÿงน Run all linters" } # === Python Version Features === -[feature.py39.dependencies] +[feature.pyoldest.dependencies] python = "3.9.*" -[feature.py313.dependencies] -python = "3.13.*" +[feature.pylatest.dependencies] +python = "3.14.*" [environments] -default = { features = ["py313"], solve-group = "py313" } -test = { features = ["test"], solve-group = "py313" } +default = { features = ["pylatest"], solve-group = "pylatest" } +test = { features = ["test"], solve-group = "pylatest" } docs = { features = [ - "py39", + "pyoldest", "docs", -], solve-group = "py39" } # TODO: change to py313 when bumping RTD theme to >=1.0 -test-py313 = { features = [ - "py313", +], solve-group = "pyoldest" } # TODO: change to pylatest when bumping RTD theme to >=1.0 +test-pylatest = { features = [ + "pylatest", "test", -], solve-group = "py313" } # alias of tests -test-py39 = { features = [ - "py39", +], solve-group = "pylatest" } # alias of test +test-pyoldest = { features = [ + "pyoldest", "test", -], solve-group = "py39" } # alias of tests +], solve-group = "pyoldest" } lint = { features = ["lint"], no-default-feature = true } From f90feae427895d6433c5a7223be54ba99275eeb9 Mon Sep 17 00:00:00 2001 From: Koyo MUNECHIKA <51052381+munechika-koyo@users.noreply.github.com> Date: Wed, 15 Jul 2026 16:56:47 +0900 Subject: [PATCH 07/18] Update channels and remove sphinx-tabs dependency Updated channels to use 'conda-forge' instead of the prefix's URL. Removed sphinx-tabs from pypi-dependencies. --- pixi.toml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/pixi.toml b/pixi.toml index d913d686..1b84805b 100644 --- a/pixi.toml +++ b/pixi.toml @@ -1,5 +1,5 @@ [workspace] -channels = ["https://prefix.dev/conda-forge"] +channels = ["conda-forge"] platforms = ["linux-64", "osx-arm64", "osx-64"] preview = ["pixi-build"] @@ -21,7 +21,6 @@ compilers = ["c"] python = ["3.9.*", "3.10.*", "3.11.*", "3.12.*", "3.13.*", "3.14.*"] [package.host-dependencies] -uv = "*" python = "*" setuptools = "*" cython = ">=3.1" @@ -89,9 +88,7 @@ test = { cmd = "python -m unittest discover cherab -v", description = "๐Ÿงช Run cherab = { path = "." } sphinx = "*" sphinx_rtd_theme = "<1" - -[feature.docs.pypi-dependencies] -sphinx-tabs = "*" # >=3.4.4 has not yet been released to conda-forge +sphinx-tabs = "*" [feature.docs.tasks] doc-build = { cmd = [ From 31aca80267265aab853df4e5f215172043719d9b Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Mon, 24 Aug 2026 11:44:15 +0200 Subject: [PATCH 08/18] Refactor pixi.toml: reorganize build configuration and clean up commands --- pixi.toml | 101 +++++++++++++++++++++++++----------------------------- 1 file changed, 46 insertions(+), 55 deletions(-) diff --git a/pixi.toml b/pixi.toml index 1b84805b..187b4ba2 100644 --- a/pixi.toml +++ b/pixi.toml @@ -3,6 +3,9 @@ channels = ["conda-forge"] platforms = ["linux-64", "osx-arm64", "osx-64"] preview = ["pixi-build"] +[workspace.build-variants] +python = ["3.9.*", "3.10.*", "3.11.*", "3.12.*", "3.13.*", "3.14.*"] + # ------------------------------- # === Packaging Configuration === # ------------------------------- @@ -10,16 +13,13 @@ preview = ["pixi-build"] name = "cherab" version = "dynamic" -[package.build] -backend = { name = "pixi-build-python", version = "*" } +[package.build.backend] +name = "pixi-build-python" +version = "*" [package.build.config] -noarch = false compilers = ["c"] -[workspace.build-variants] -python = ["3.9.*", "3.10.*", "3.11.*", "3.12.*", "3.13.*", "3.14.*"] - [package.host-dependencies] python = "*" setuptools = "*" @@ -30,6 +30,8 @@ raysect = "0.9.*" [package.run-dependencies] scipy = "*" matplotlib-base = "*" + +[package.extra-dependencies.opencl] pyopencl = "*" pocl = "*" @@ -39,49 +41,40 @@ pocl = "*" [dependencies] ipython = "*" +[dev] +cherab = { path = "." } + [tasks] -clean = { cmd = [ - "find", - "cherab/", - "-type", - "f", - "\\(", - "-name", - "'*.c'", - "-o", - "-name", - "'*.so'", - "-o", - "-name", - "'*.dylib'", - "-o", - "-name", - "'*.html'", - "\\)", - "-delete", -], description = "๐Ÿ”ฅ Remove in-place build artifacts and temporary files (*.c, *.so, *.dylib)" } +clean = { + cmd = "find cherab -type f \\( -name '*.c' -o -name '*.so' -o -name '*.pyd' -o -name '*.dll' -o -name '*.html' \\) -delete", + description = "๐Ÿ”ฅ Remove in-place build artifacts and temporary files (*.c, *.so, *.pyd, *.dll, *.html)", +} # The documentation-related tasks below do not require the source package. -doc-clean = { cmd = [ - "rm", - "-rf", - "build", -], cwd = "docs", description = "๐Ÿ”ฅ Clean the docs build directory" } -doc-serve = { cmd = [ - "python", - "-m", - "http.server", - "8000", - "--directory", - "build/html", -], cwd = "docs", description = "๐Ÿš€ Start a local server for the docs" } +doc-clean = { + cmd = "rm -rf build", + cwd = "docs", + description = "๐Ÿ”ฅ Clean the docs build directory", +} # === Testing feature === [feature.test.dependencies] cherab = { path = "." } [feature.test.tasks] -test = { cmd = "python -m unittest discover cherab -v", description = "๐Ÿงช Run the tests" } +test = { + cmd = "python -m unittest discover cherab -v", + description = "๐Ÿงช Run the tests", +} + +[feature.test-opencl.dependencies] +cherab = { path = ".", extras = ["opencl"] } + +[feature.test-opencl.tasks] +test-opencl = { + cmd = "python -m unittest cherab.tools.tests.test_sart_opencl -v", + description = "๐Ÿงช Run the OpenCL tests", +} # === Documentation feature === [feature.docs.dependencies] @@ -91,15 +84,20 @@ sphinx_rtd_theme = "<1" sphinx-tabs = "*" [feature.docs.tasks] -doc-build = { cmd = [ +doc-build = { + cmd = [ "sphinx-build", "-b", "{{ target }}", "source", "build/{{ target }}", -], cwd = "docs", args = [ + ], + cwd = "docs", + args = [ { arg = "target", default = "html" }, -], description = "๐Ÿ“ Build the docs" } + ], + description = "๐Ÿ“ Build the docs" +} # === Linting feature === [feature.lint.dependencies] @@ -132,22 +130,15 @@ lint = { cmd = "lefthook run pre-commit --all-files --force", description = " # === Python Version Features === [feature.pyoldest.dependencies] python = "3.9.*" + [feature.pylatest.dependencies] python = "3.14.*" [environments] default = { features = ["pylatest"], solve-group = "pylatest" } test = { features = ["test"], solve-group = "pylatest" } -docs = { features = [ - "pyoldest", - "docs", -], solve-group = "pyoldest" } # TODO: change to pylatest when bumping RTD theme to >=1.0 -test-pylatest = { features = [ - "pylatest", - "test", -], solve-group = "pylatest" } # alias of test -test-pyoldest = { features = [ - "pyoldest", - "test", -], solve-group = "pyoldest" } +docs = { features = ["pyoldest", "docs"], solve-group = "pyoldest" } # TODO: change to pylatest when bumping RTD theme to >=1.0 +test-pylatest = { features = ["pylatest", "test"], solve-group = "pylatest" } # alias of test +test-pyoldest = { features = ["pyoldest", "test"], solve-group = "pyoldest" } +test-opencl = { features = ["test-opencl"], solve-group = "pyoldest" } lint = { features = ["lint"], no-default-feature = true } From 36763a053e5eb6d9e230a285f3ab190a62b0982f Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Mon, 24 Aug 2026 13:11:47 +0200 Subject: [PATCH 09/18] Add doc-serve task to start a local server for documentation --- pixi.toml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/pixi.toml b/pixi.toml index 187b4ba2..8ae3b640 100644 --- a/pixi.toml +++ b/pixi.toml @@ -56,6 +56,21 @@ doc-clean = { cwd = "docs", description = "๐Ÿ”ฅ Clean the docs build directory", } +doc-serve = { + cmd = [ + "python", + "-m", + "http.server", + "{{ port }}", + "--directory", + "build/html", + ], + cwd = "docs", + args = [ + { arg = "port", default = "8000" }, + ], + description = "๐Ÿš€ Start a local server for the docs", +} # === Testing feature === [feature.test.dependencies] From e68716147cfe4e5ee8d143a176ec89a35115640e Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Mon, 24 Aug 2026 13:28:22 +0200 Subject: [PATCH 10/18] Replace taplo with tombi for TOML formatting in lint tasks --- pixi.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pixi.toml b/pixi.toml index 8ae3b640..0c90842e 100644 --- a/pixi.toml +++ b/pixi.toml @@ -125,7 +125,7 @@ shellcheck = "*" validate-pyproject = "*" cython-lint = "*" blacken-docs = "*" -taplo = "*" +tombi = "*" [feature.lint.tasks] lefthook = { cmd = "lefthook", description = "๐Ÿ”— Run lefthook" } @@ -133,9 +133,9 @@ hooks = { cmd = "lefthook install", description = "๐Ÿ”— Install pre-commit hooks pre-commit = { cmd = "lefthook run pre-commit", description = "๐Ÿ”— Run pre-commit checks" } ruff-check = { cmd = "ruff check", description = "Lint with ruff" } ruff-format = { cmd = "ruff format", description = "Format with ruff" } +toml-format = { cmd = "tombi format", description = "Format TOML files" } dprint = { cmd = "dprint fmt", description = "Format with dprint" } typos = { cmd = "typos --write-changes --force-exclude", description = "Fix typos" } -taplo = { cmd = "taplo fmt", description = "Format toml files with taplo" } actionlint = { cmd = "actionlint", description = "Lint actions with actionlint" } blacken-docs = { cmd = "blacken-docs", description = "Format Python markdown blocks with Black" } validate-pyproject = { cmd = "validate-pyproject pyproject.toml", description = "Validate pyproject.toml" } From b8d5f284a101322289079382ea33d7de8843ca6f Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Mon, 24 Aug 2026 13:38:28 +0200 Subject: [PATCH 11/18] Add Pixi developer guide with environment and task documentation --- dev/pixi.md | 180 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 dev/pixi.md diff --git a/dev/pixi.md b/dev/pixi.md new file mode 100644 index 00000000..0856e819 --- /dev/null +++ b/dev/pixi.md @@ -0,0 +1,180 @@ +# ๐Ÿงฐ Pixi developer guide + +This document describes the development environments and tasks configured in +[`pixi.toml`](../pixi.toml). Pixi manages the development dependencies in +isolated environments and provides a common interface for running tests, +building the documentation, and checking the source tree. + +Pixi installs or updates the selected environment automatically when a command +is run. The workspace currently supports Linux x86-64, macOS x86-64, and macOS +Arm64. + +## ๐Ÿ”Ž Discovering tasks + +List every task in the workspace with: + +```console +pixi task list +``` + +To show only the tasks available in a particular environment, pass its name: + +```console +pixi task list -e test +``` + +Use `pixi run --help` for general command help. When a task is available in +more than one environment, use `-e ` to select the environment +explicitly. + +## ๐Ÿงฉ Environments + +| Environment | Purpose | +| --- | --- | +| `default` | Basic development tools; Cherab is not installed | +| `test` | Run the complete test suite using the latest supported Python; currently equivalent to `test-pylatest` | +| `test-pylatest` | Run the complete test suite using the latest supported Python | +| `test-pyoldest` | Run the complete test suite using the oldest supported Python | +| `test-opencl` | Run the OpenCL SART tests with Cherab's `opencl` extra | +| `docs` | Build the documentation | +| `lint` | Run formatting and static-analysis tools without installing Cherab | + +See the [`pyoldest` and `pylatest` features and environment definitions in +`pixi.toml`](../pixi.toml#L145-L159) for the Python versions used by each +environment. + +## ๐Ÿ› ๏ธ Basic development tasks + +Start an IPython session in the default environment: + +```console +pixi run ipython +``` + +Remove generated C/Cython libraries and HTML files from the `cherab/` source +tree: + +```console +pixi run clean +``` + +The `clean` task deletes files matching `*.c`, `*.so`, `*.pyd`, `*.dll`, and +`*.html` below `cherab/`. + +## ๐Ÿงช Testing + +Run the complete test suite with the latest supported Python: + +```console +pixi run -e test test +``` + +The `test` environment currently uses the same solve group as +`test-pylatest`. The explicit alias can also be used: + +```console +pixi run -e test-pylatest test +``` + +Run the suite with the oldest supported Python: + +```console +pixi run -e test-pyoldest test +``` + +Run the OpenCL SART tests: + +```console +pixi run -e test-opencl test-opencl +``` + +The regular test task runs `python -m unittest discover cherab -v`. The OpenCL +task runs `cherab.tools.tests.test_sart_opencl` only. + +## ๐Ÿ“š Documentation + +Build the HTML documentation: + +```console +pixi run -e docs doc-build +``` + +`html` is the default Sphinx builder. A different builder can be supplied as +the final argument; for example, check external and internal links with: + +```console +pixi run -e docs doc-build linkcheck +``` + +Build output is written below `docs/build/`. Remove all documentation +build output with: + +```console +pixi run doc-clean +``` + +After building the HTML documentation, serve it locally on port 8000 with: + +```console +pixi run doc-serve +``` + +Then open in a browser. To use a different port, pass +it as the final argument: + +```console +pixi run doc-serve 8080 +``` + +## ๐Ÿงน Formatting and static analysis + +The `lint` environment keeps code-quality tools separate from the environments +that build and install Cherab. Because the task names below are unique to this +environment, Pixi selects it automatically; `-e lint` is not required. + +| Task | Action | +| --- | --- | +| `lefthook` | Run Lefthook | +| `hooks` | Install the Git hooks managed by Lefthook | +| `pre-commit` | Run the Lefthook `pre-commit` group | +| `ruff-check` | Run `ruff check` | +| `ruff-format` | Run `ruff format` | +| `toml-format` | Run `tombi format` | +| `dprint` | Run `dprint fmt` | +| `typos` | Find and fix spelling errors | +| `actionlint` | Run Actionlint | +| `blacken-docs` | Format Python examples in documentation | +| `validate-pyproject` | Validate `pyproject.toml` | +| `cython-lint` | Run Cython-Lint | +| `lint` | Run the Lefthook `pre-commit` group on all files | + +For example: + +```console +pixi run ruff-check +pixi run toml-format +pixi run cython-lint +pixi run validate-pyproject +``` + +The `hooks`, `lefthook`, `pre-commit`, and aggregate `lint` tasks invoke +Lefthook. + +> [!WARNING] +> A Lefthook configuration file has not been added to the repository yet, so +> these tasks are not currently available. + +Install the Git hooks and run all configured checks with: + +```console +pixi run hooks +pixi run lint +``` + +Running `pixi run hooks` installs the Git hooks once. After installation, the +configured pre-commit checks are triggered automatically for every commit. To +remove the installed hooks and stop the automatic checks, run: + +```console +pixi run lefthook uninstall +``` From e69f53cfd50aecd7abed2f3c58c118116be556f0 Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Mon, 24 Aug 2026 14:45:35 +0200 Subject: [PATCH 12/18] Fix links in Pixi developer guide and remove top header's emoji --- dev/pixi.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/dev/pixi.md b/dev/pixi.md index 0856e819..2786e641 100644 --- a/dev/pixi.md +++ b/dev/pixi.md @@ -1,9 +1,10 @@ -# ๐Ÿงฐ Pixi developer guide +# Pixi developer guide This document describes the development environments and tasks configured in -[`pixi.toml`](../pixi.toml). Pixi manages the development dependencies in -isolated environments and provides a common interface for running tests, -building the documentation, and checking the source tree. +[`pixi.toml`](https://github.com/cherab/core/blob/development/pixi.toml). Pixi +manages the development dependencies in isolated environments and provides a +common interface for running tests, building the documentation, and checking +the source tree. Pixi installs or updates the selected environment automatically when a command is run. The workspace currently supports Linux x86-64, macOS x86-64, and macOS @@ -40,8 +41,8 @@ explicitly. | `lint` | Run formatting and static-analysis tools without installing Cherab | See the [`pyoldest` and `pylatest` features and environment definitions in -`pixi.toml`](../pixi.toml#L145-L159) for the Python versions used by each -environment. +`pixi.toml`](https://github.com/cherab/core/blob/development/pixi.toml#L146-L160) +for the Python versions used by each environment. ## ๐Ÿ› ๏ธ Basic development tasks From 3890c0ed9c67627c591b6cf06fa53cb4940427c9 Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Mon, 24 Aug 2026 14:46:21 +0200 Subject: [PATCH 13/18] Add myst-parser dependency for documentation generation --- pixi.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pixi.toml b/pixi.toml index 0c90842e..250fc291 100644 --- a/pixi.toml +++ b/pixi.toml @@ -97,6 +97,7 @@ cherab = { path = "." } sphinx = "*" sphinx_rtd_theme = "<1" sphinx-tabs = "*" +myst-parser = "*" [feature.docs.tasks] doc-build = { From c596630a10496b2cb79d42aea6e83c441e285745 Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Mon, 24 Aug 2026 14:47:09 +0200 Subject: [PATCH 14/18] Add myst_parser extension and update documentation structure for development --- docs/source/conf.py | 1 + docs/source/development/pixi.rst | 2 ++ docs/source/index.rst | 9 ++++++++- 3 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 docs/source/development/pixi.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index b2f22c70..c268831e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -40,6 +40,7 @@ 'sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'sphinx_tabs.tabs', + 'myst_parser', ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/source/development/pixi.rst b/docs/source/development/pixi.rst new file mode 100644 index 00000000..0be6bd02 --- /dev/null +++ b/docs/source/development/pixi.rst @@ -0,0 +1,2 @@ +.. include:: ../../../dev/pixi.md + :parser: myst_parser.sphinx_ diff --git a/docs/source/index.rst b/docs/source/index.rst index 3e3e90ce..72f6cda6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -28,6 +28,14 @@ become stable until we have finished moving the source code to github. tools/tools +.. toctree:: + :maxdepth: 2 + :caption: Development + :name: development + + development/pixi + + .. toctree:: :maxdepth: 2 :caption: Demonstrations @@ -41,4 +49,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` - From 05ca189198645fe85e5ce1395d1b7837e574a674 Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Mon, 24 Aug 2026 14:57:59 +0200 Subject: [PATCH 15/18] Update link to Python version features in Pixi developer guide --- dev/pixi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev/pixi.md b/dev/pixi.md index 2786e641..6b19fa1a 100644 --- a/dev/pixi.md +++ b/dev/pixi.md @@ -41,7 +41,7 @@ explicitly. | `lint` | Run formatting and static-analysis tools without installing Cherab | See the [`pyoldest` and `pylatest` features and environment definitions in -`pixi.toml`](https://github.com/cherab/core/blob/development/pixi.toml#L146-L160) +`pixi.toml`](https://github.com/cherab/core/blob/development/pixi.toml#:~:text=Python%20Version%20Features) for the Python versions used by each environment. ## ๐Ÿ› ๏ธ Basic development tasks From 5f63cec0be3e4df7de9f218a15cfbdd1bd8574bd Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Mon, 24 Aug 2026 14:59:20 +0200 Subject: [PATCH 16/18] Add pixi feature into changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 513c1bc1..bc9d8b42 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ Bug fixes: * Fix the import statement for `netcdf_file` in `calcam.py` for compatibility with the upcoming `scipy` v2.0.0. (#510) New: +* Add an optional Pixi workspace for package builds and isolated development environments, with tasks for testing, documentation, formatting, and static analysis, and include the corresponding developer guide in the Sphinx documentation. (#489) * Add GaussianQuadrature2D integrator. (#475) * Support Raysect 0.9. (#486) * Test against Python 3.9, 3.10, 3.11, 3.12, 3.13 and latest released Numpy. Drop Python 3.7, 3.8 and older Numpy from tests. (#486) From 0c5fbed5d8988de07e437215c844a8f5677845a7 Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Tue, 25 Aug 2026 08:03:21 +0200 Subject: [PATCH 17/18] Add TODO comment about sphinx_rtd_theme version constraint --- pixi.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pixi.toml b/pixi.toml index 250fc291..7f9dd08d 100644 --- a/pixi.toml +++ b/pixi.toml @@ -95,7 +95,7 @@ test-opencl = { [feature.docs.dependencies] cherab = { path = "." } sphinx = "*" -sphinx_rtd_theme = "<1" +sphinx_rtd_theme = "<1" # TODO: change to >=1.0 when our docs layout is compatible with the new theme sphinx-tabs = "*" myst-parser = "*" From 9aee81b4a3328b51cbfa2624e6be1e83ec4061b7 Mon Sep 17 00:00:00 2001 From: munechika-koyo Date: Tue, 25 Aug 2026 08:05:41 +0200 Subject: [PATCH 18/18] Format python version constraints in pixi.toml for better readability --- pixi.toml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/pixi.toml b/pixi.toml index 7f9dd08d..64d3c551 100644 --- a/pixi.toml +++ b/pixi.toml @@ -4,7 +4,14 @@ platforms = ["linux-64", "osx-arm64", "osx-64"] preview = ["pixi-build"] [workspace.build-variants] -python = ["3.9.*", "3.10.*", "3.11.*", "3.12.*", "3.13.*", "3.14.*"] +python = [ + "3.9.*", + "3.10.*", + "3.11.*", + "3.12.*", + "3.13.*", + "3.14.*", +] # ------------------------------- # === Packaging Configuration ===