docs: Use uv for managing Python and dependencies

Python packaging is in flux, but the old form of requirements
(`requirements.txt`) is no longer recommended. The use of a More modern
alternative (such as Poetry, PDM, Rye, or uv) is recommended as they
also provide dependency lock files so that downstream dependencies are
not updated on installation.

For a project that is not written in Python, `uv` looks likely to be the
best choice because it can also manage the Python installation, using a
suitable existing Python installation if present.

As `uv` does not currently support running tasks (unlike Poetry and
pdm), we have added `taskipy` with useful shorthand tasks defined for
this purpose:

| name        | command                                      |
| ----------- | -------------------------------------------- |
| build-docs  | mkdocs build -f assets/chezmoi.io/mkdocs.yml |
| serve-docs  | mkdocs serve -f assets/chezmoi.io/mkdocs.yml |
| deploy-docs | cd assets/chezmoi.io && mkdocs gh-deploy     |
| lint        | ruff check                                   |
| format      | ruff format                                  |
| pycheck     | task lint && task format --diff              |
| pyfix       | task lint --fix && task format               |
| format-yaml | make format-yaml                             |

These are run with `uv run task <name>`. Note that `make format-yaml`
is the preferred way to format YAML documents, and it runs the
`format-yaml.py` script directly.`

.github/workflows/main.yml

@@ -22,7 +22,9 @@ env:
   GOLINES_VERSION: 0.12.2 # https://github.com/segmentio/golines/releases
   GORELEASER_VERSION: 2.3.2 # https://github.com/goreleaser/goreleaser/releases
   GOVERSIONINFO_VERSION: 1.4.1 # https://github.com/josephspurrier/goversioninfo/releases
+  PYTHON_VERSION: '3.10'
   RAGE_VERSION: 0.10.0 # https://github.com/str4d/rage/releases
+  UV_VERSION: 0.4.15 # https://github.com/astral-sh/uv/releases
 jobs:
   changes:
     runs-on: ubuntu-22.04
@@ -282,11 +284,15 @@ jobs:
     - uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32
       with:
         go-version: ${{ env.GO_VERSION }}
+    - uses: astral-sh/setup-uv@abac0ce7b0768476333db78faaf98b1130f5face
+      with:
+        version: ${{ env.UV_VERSION }}
     - name: install-website-dependencies
       run: |
-        pip3 install -r assets/chezmoi.io/requirements.txt
+        uv python install ${{ env.PYTHON_VERSION }}
+        uv sync --locked
     - name: build-website
-      run: mkdocs build -f assets/chezmoi.io/mkdocs.yml
+      run: uv run -v task build-docs
       env:
         CHEZMOI_GITHUB_TOKEN: ${{ secrets.CHEZMOI_GITHUB_TOKEN }}
   test-windows:
@@ -450,15 +456,19 @@ jobs:
     - uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32
       with:
         go-version: ${{ env.GO_VERSION }}
+    - uses: astral-sh/setup-uv@abac0ce7b0768476333db78faaf98b1130f5face
+      with:
+        version: ${{ env.UV_VERSION }}
     - name: prepare-chezmoi.io
       run: |
-        pip3 install -r assets/chezmoi.io/requirements.txt
-        mkdocs build -f assets/chezmoi.io/mkdocs.yml
+        uv sync --locked
+        uv python install ${{ env.PYTHON_VERSION }}
+        uv run -v task build-docs
       env:
         CHEZMOI_GITHUB_TOKEN: ${{ secrets.CHEZMOI_GITHUB_TOKEN }}
     - name: push-chezmoi.io
       run: |
-        ( cd assets/chezmoi.io && mkdocs gh-deploy )
+        uv run -v task deploy-docs
     - name: prepare-get.chezmoi.io
       run: |
         cp assets/scripts/install.sh assets/get.chezmoi.io/index.html

Makefile

@@ -131,7 +131,7 @@ format: ensure-gofumpt ensure-golines
 
 .PHONY: format-yaml
 format-yaml:
-	find . -name \*.yaml -o -name \*.yml | xargs ./assets/scripts/format-yaml.py
+	find . -name \*.yaml -o -name \*.yml | xargs uv run ./assets/scripts/format-yaml.py
 
 .PHONY: create-syso
 create-syso: ensure-goversioninfo

assets/chezmoi.io/docs/developer-guide/website.md

@@ -1,56 +1,43 @@
 # Website
 
-The [website](https://chezmoi.io) is generated with [Material for
-MkDocs](https://squidfunk.github.io/mkdocs-material/) from the contents of the
-`assets/chezmoi.io/docs/` directory. It is hosted by [GitHub
-pages](https://pages.github.com/) from the [`gh-pages`
-branch](https://github.com/twpayne/chezmoi/tree/gh-pages).
+The [website](https://chezmoi.io) is generated with
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) from the
+contents of the `assets/chezmoi.io/docs/` directory. It is hosted by
+[GitHub pages](https://pages.github.com/) from the
+[`gh-pages` branch](https://github.com/twpayne/chezmoi/tree/gh-pages).
 
-To build the website locally, both Go 1.22 (or later) and Python 3.10 (or later)
-must be installed.
-
-Change into the website directory:
-
-```console
-$ cd assets/chezmoi.io
-```
+To build the website locally, Go 1.22 (or later) and
+[uv](https://docs.astral.sh/uv/getting-started/installation/) 0.4.15 (or later)
+must be installed. Python 3.10 (or later) is required, but may be installed with
+`uv`:
 
 !!! note ""
 
-    === "Default"
-
-        Install the website dependencies:
-
-        ```console
-        $ pip3 install --user -r requirements.txt
-        ```
+    If Python 3.10 (or later) is not currently installed, install it with `uv`:
 
-    === "virtualenv (Recommended)"
+    ```console
+    $ uv python install 3.10
+    ```
 
-        Create a virtualenv with:
+Install the dependencies (the `--frozen` is optional but recommended):
 
-        ```console
-        $ python3 -m venv .venv
-        ```
-
-        and [activate it](https://docs.python.org/3/library/venv.html#how-venvs-work).
-
-        Install the website dependencies:
-
-        ```console
-        $ pip3 install -r requirements.txt
-        ```
+```console
+$ uv sync --frozen
+```
 
 Test the website locally by running:
 
 ```console
-$ mkdocs serve
+$ uv run task serve-docs
 ```
 
 and visiting [http://127.0.0.1:8000/](http://127.0.0.1:8000/).
 
-Deploy the website with:
+## Maintainers
+
+The website is automatically deployed when new releases are created, but manual
+deployments can be triggered by maintainers with appropriate access using:
 
 ```console
-$ mkdocs gh-deploy
+$ uv run task mkdocs gh-deploy
 ```

pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "chezmoi"
+version = "2.52.2"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+
+[tool.uv]
+dev-dependencies = [
+  "ruff==0.6.7",
+  "mkdocs-material==9.5.34",
+  "mkdocs-mermaid2-plugin==1.1.1",
+  "mkdocs==1.6.1",
+  "pymdown-extensions==10.10.1",
+  "ruamel-yaml==0.18.6",
+  "taskipy==1.13.0",
+]
+
+[tool.taskipy.tasks]
+build-docs = { cmd = "mkdocs build -f assets/chezmoi.io/mkdocs.yml" }
+serve-docs = { cmd = "mkdocs serve -f assets/chezmoi.io/mkdocs.yml" }
+deploy-docs = { cmd = "cd assets/chezmoi.io && mkdocs gh-deploy" }
+lint = { cmd = "ruff check" }
+format = { cmd = "ruff format" }
+pycheck = { cmd = "task lint && task format --diff" }
+pyfix = { cmd = "task lint --fix && task format" }
+format-yaml = { cmd = "make format-yaml" }
+
+[tool.ruff]
+include = [
+  "pyproject.toml",
+  "assets/chezmoi.io/docs/hooks.py",
+  "assets/chezmoi.io/docs/shortcodes.py",
+  "assets/scripts/format-yaml.py",
+]
+target-version = "py310"
+
+[tool.ruff.lint]
+extend-select = [
+  "A",
+  "B",
+  "E",
+  "F",
+  "I",
+  "W",
+  "ANN",
+  "COM",
+  "FA",
+  "UP",
+  "PL",
+  "PTH",
+  "SIM",
+]
+ignore = ["ANN003", "COM812"]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.uv.workspace]
+members = ["chezmoi"]