docs: migrate from Poetry to uv

.gitattributes

@@ -1,3 +1,3 @@
 Cargo.lock linguist-generated=true merge=binary
 flake.lock linguist-generated=true merge=binary
-poetry.lock linguist-generated=true merge=binary
+uv.lock linguist-generated=true merge=binary

.github/scripts/docs-build-deploy

@@ -4,7 +4,7 @@
 # Run from the root directory of the project as
 # .github/scripts/docs-build-deploy 'https://martinvonz.github.io' prerelease main
 # All arguments after the first are passed to `mike deploy`, run
-# `poetry run -- mike deploy --help` for options. Note that `mike deploy`
+# `uv run -- mike deploy --help` for options. Note that `mike deploy`
 # creates a commit directly on the `gh-pages` branch.
 set -ev
 
@@ -13,15 +13,11 @@ export "SITE_URL_FOR_MKDOCS=$1"; shift
 # https://github.com/jimporter/mike/issues/103 and
 # https://reproducible-builds.org/docs/source-date-epoch/
 export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct docs/ mkdocs.yml)
-# https://github.com/python-poetry/poetry/issues/1917 and
-# https://github.com/python-poetry/poetry/issues/8623
-export PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring
-poetry install  # Only really needed once per environment unless there are updates
 # TODO: `--alias-type symlink` is the
 # default, and may be nicer in some ways. However,
 # this requires deploying to GH Pages via a "custom GitHub Action", as in
 # https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow.
 # Otherwise, you get an error:
 # > Site contained a symlink that should be dereferenced: /main.
 # > For more information, see https://docs.github.com/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#config-file-error.
-poetry run -- mike deploy --alias-type copy "$@"
+uv run -- mike deploy --alias-type copy "$@"

.github/workflows/build.yml

@@ -43,7 +43,7 @@ jobs:
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
 
     # The default version of gpg installed on the runners is a version baked in with git
-    # which only contains the components needed by git and doesn't work for our test cases. 
+    # which only contains the components needed by git and doesn't work for our test cases.
     #
     # This installs the latest gpg4win version, which is a variation of GnuPG built for
     # Windows.
@@ -126,37 +126,27 @@ jobs:
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
         with:
           python-version: 3.11
-      - name: Install poetry (latest release)
-        uses: abatilo/actions-poetry@e78f54a89cb052fff327414dd9ff010b5d2b4dbd
+      - name: Install uv
+        uses: astral-sh/setup-uv@2e657c127d5b1635d5a8e3fa40e0ac50a5bf6992
         with:
-          poetry-version: latest
-      - name: Install dependencies
-        run: poetry install 
+          # If you bump the version, also update docs/contributing.md
+          # and all other workflows that install uv
+          version: "0.5.1"
       - name: Check that `mkdocs` can build the docs
-        run: poetry run -- mkdocs build --strict
+        run: uv run -- mkdocs build --strict
 
-  mkdocs-old-poetry:
-    name: Check that MkDocs can build the docs with Poetry 1.8
+  # An optional job to alert us when uv updates break the build
+  mkdocs-latest:
+    name: Check that MkDocs can build the docs with latest Python and uv
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
-        with:
-          python-version: 3.11
-      - name: Install poetry
-        uses: abatilo/actions-poetry@e78f54a89cb052fff327414dd9ff010b5d2b4dbd
-        with:
-          # Test with the version of Poetry in Debian stable. If this starts
-          # failing, we should increase this version and document the minimum
-          # necessary version of Poetry in contributing.md.
-          #
-          # One way to install old `poetry` is using `pipx`:
-          #    pipx install 'poetry<1.4' --suffix -1.3
-          poetry-version: 1.8
-      - name: Install dependencies
-        run: poetry install 
+      - name: Install uv
+        uses: astral-sh/setup-uv@2e657c127d5b1635d5a8e3fa40e0ac50a5bf6992
+      # 'only-managed' means that uv will always download Python, even
+      # if the runner happens to provide a compatible version
       - name: Check that `mkdocs` can build the docs
-        run: poetry run -- mkdocs build --strict
+        run: uv run --python-preference=only-managed -- mkdocs build --strict
 
   cargo-deny:
     runs-on: ubuntu-latest

.github/workflows/docs.yml

@@ -22,10 +22,10 @@ jobs:
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
         with:
           python-version: 3.11
-      - name: Install poetry
-        uses: abatilo/actions-poetry@e78f54a89cb052fff327414dd9ff010b5d2b4dbd
+      - name: Install uv
+        uses: astral-sh/setup-uv@2e657c127d5b1635d5a8e3fa40e0ac50a5bf6992
         with:
-          poetry-version: latest
+          version: "0.5.1"
       - name: Install dependencies, compile and deploy docs
         run: |
           git config user.name 'jj-docs[bot]'

.github/workflows/release.yml

@@ -100,14 +100,13 @@ jobs:
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
         with:
           python-version: 3.11
-      - name: Install poetry
-        uses: abatilo/actions-poetry@e78f54a89cb052fff327414dd9ff010b5d2b4dbd
+      - name: Install uv
+        uses: astral-sh/setup-uv@2e657c127d5b1635d5a8e3fa40e0ac50a5bf6992
         with:
-          poetry-version: latest
+          version: "0.5.1"
       - name: Compile docs and zip them up
         run: |
-          poetry install 
-          poetry run -- mkdocs build -f mkdocs-offline.yml
+          uv run -- mkdocs build -f mkdocs-offline.yml
           archive="jj-${{ github.event.release.tag_name }}-docs-html.tar.gz"
           tar czf "$archive" -C "rendered-docs" .
           echo "ASSET=$archive" >> $GITHUB_ENV
@@ -132,10 +131,10 @@ jobs:
       - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
         with:
           python-version: 3.11
-      - name: Install poetry
-        uses: abatilo/actions-poetry@e78f54a89cb052fff327414dd9ff010b5d2b4dbd
+      - name: Install uv
+        uses: astral-sh/setup-uv@2e657c127d5b1635d5a8e3fa40e0ac50a5bf6992
         with:
-          poetry-version: latest
+          version: "0.5.1"
       - name: Install dependencies, compile and deploy docs to the "latest release" section of the website
         run: |
           git config user.name 'jj-docs[bot]'

.gitignore

@@ -9,6 +9,10 @@ result
 *.snap*
 !cli/tests/[email protected]
 
+# mkdocs
+/.venv
+/.python-version
+
 # Editor specific ignores
 .idea
 .vscode

docs/contributing.md

@@ -269,64 +269,85 @@ We recommend at least these settings:
 
 ## Previewing the HTML documentation
 
-The documentation for `jj` is automatically published to the website at
+The documentation for `jj` is automatically published online at
 <https://martinvonz.github.io/jj/>.
 
-When editing documentation, we'd appreciate it if you checked that the
-result will look as expected when published to the website.
+When editing documentation, you should check your changes locally — especially
+if you are adding a new page, or doing a major rewrite.
 
-### Setting up the prerequisites
+### Install `uv`
 
-To build the website, you must have Python and `poetry 1.8+` installed (the
-latest version is recommended). It is easiest to install `poetry` via `pipx`, as
-explained in the [Poetry installation instructions]. A few helpful points from
-the instructions: `pipx` can often be installed from your distribution, e.g.
-`sudo apt install pipx`; this will usually also install Python for you if
-necessary. Any version of `pipx` will do. If you are installing `pipx` manually,
-you may first need to follow the [Python installation instructions].
+The only thing you need is [`uv`][uv] (version 0.5.1 or newer).
 
-[Python installation instructions]: https://docs.python.org/3/using/index.html
-[Poetry installation instructions]: https://python-poetry.org/docs/#installation
+`uv` is a Python project manager written in Rust. It will fetch the right Python
+version and the dependencies needed to build the docs. Install it like so:
 
-Once you have `poetry` installed, you should ask it to install the rest
-of the required tools into a virtual environment as follows:
+[uv]: https://docs.astral.sh/uv/
 
-```shell
-poetry install
-```
+=== "macOS/Linux"
 
-You may get requests to "unlock a keyring", [an error messages about failing to
-do so](https://github.com/python-poetry/poetry/issues/1917), or Poetry may
-[simply hang indefinitely](https://github.com/python-poetry/poetry/issues/8623).
-The workaround is to either to unlock the keyring or to run the following, and
-then to try `poetry install` again:
+    ``` { .shell .copy }
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    ```
 
-```shell
-# For sh-compatible shells or recent versions of `fish`
-export PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring
-```
+    !!! note
+        If you don't have `~/.local/bin` in your `PATH`, the installer will
+        modify your shell profile. To avoid it:
 
-### Building the HTML docs locally (with live reload)
+        ``` { .shell .copy }
+        curl -LsSf https://astral.sh/uv/install.sh | env INSTALLER_NO_MODIFY_PATH=1 sh
+        ```
 
-The HTML docs are built with [MkDocs](https://github.com/mkdocs/mkdocs). After
-following the above steps, you should be able to view the docs by running
+=== "Windows"
 
-```shell
-# Note: this and all the commands below should be run from the root of
-# the `jj` source tree.
-poetry run -- mkdocs serve
+    ``` { .shell .copy }
+    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+    ```
+
+=== "Homebrew"
+
+    ``` { .shell .copy }
+    brew install uv
+    ```
+
+=== "Cargo"
+
+    ``` { .shell .copy }
+    # This might take a while
+    cargo install --git https://github.com/astral-sh/uv uv
+    ```
+
+=== "Other options"
+
+    * Directly download the binaries from GitHub: [uv releases](https://github.com/astral-sh/uv/releases).
+    * Even more options: [Installing uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+### Build the docs
+
+To build the docs, run from the root of the `jj` repository:
+
+``` { .shell .copy }
+uv run mkdocs serve
 ```
 
-and opening <http://127.0.0.1:8000> in your browser.
+Open <http://127.0.0.1:8000> in your browser to see the docs.
+
+As you edit the `.md` files in `docs/`, the website should be rebuilt and
+reloaded in your browser automatically.
+
+!!! note "If the docs are not updating"
+    Check the terminal from which you ran `uv run mkdocs serve` for any build
+    errors or warnings. Warnings about `"GET /versions.json HTTP/1.1" code 404`
+    are expected and harmless.
 
-As you edit the `md` files, the website should be rebuilt and reloaded in your
-browser automatically, unless build errors occur.
+## Building the entire website
 
-You should occasionally check the terminal from which you ran `mkdocs serve` for
-any build errors or warnings. Warnings about `"GET /versions.json HTTP/1.1" code
-404` are expected and harmless.
+!!! tip
+    Building the entire website is not usually necessary. If you are editing
+    documentation, the previous section is enough.
 
-### How to build the entire website (not usually necessary)
+    These instructions are relevant if you are working on the versioning of the
+    documentation that we currently do with `mike`.
 
 The full `jj` website includes the documentation for several `jj` versions
 (`prerelease`, latest release, and the older releases). The top-level
@@ -336,22 +357,24 @@ the docs for the last stable version.
 
 The different versions of documentation are managed and deployed with
 [`mike`](https://github.com/jimporter/mike), which can be run with
-`poetry run -- mike`.
+`uv run mike`.
 
 On a POSIX system or WSL, one way to build the entire website is as follows (on
 Windows, you'll need to understand and adapt the shell script):
 
 1. Check out `jj` as a co-located `jj + git` repository (`jj clone --colocate`),
-cloned from your fork of `jj` (e.g. `jjfan.github.com/jj`). You can also use a
+cloned from your fork of `jj` (e.g. `github.com/jjfan/jj`). You can also use a
 pure Git repo if you prefer.
 
-2. Make sure `jjfan.github.com/jj` includes the `gh-pages` bookmark of the jj repo
+2. Make sure `github.com/jjfan/jj` includes the `gh-pages` bookmark of the jj repo
 and run `git fetch origin gh-pages`.
 
 3. Go to the GitHub repository settings, enable GitHub Pages, and configure them
 to use the `gh-pages` bookmark (this is usually the default).
 
-4. Run the same `sh` script that is used in GitHub CI (details below):
+4. Install `uv` as explained in [Previewing the HTML
+documentation](#previewing-the-html-documentation), and run the same `sh` script
+that is used in GitHub CI (details below):
 
     ```shell
     .github/scripts/docs-build-deploy 'https://jjfan.github.io/jj/'\
@@ -390,18 +413,18 @@ this can be done with:
     If you want to preserve some of the changes you made, you can do `jj bookmark
     set my-changes -r gh-pages` BEFORE running the above commands.
 
-#### Explanation of the `docs-build-deploy` script
+### Explanation of the `docs-build-deploy` script
 
 The script sets up the `site_url` mkdocs config to
 `'https://jjfan.github.io/jj/'`. If this config does not match the URL
 where you loaded the website, some minor website features (like the
 version switching widget) will have reduced functionality.
 
-Then, the script passes the rest of its arguments to `potery run -- mike
-deploy`, which does the rest of the job. Run `poetry run -- mike help deploy` to
+Then, the script passes the rest of its arguments to `uv run mike
+deploy`, which does the rest of the job. Run `uv run mike help deploy` to
 find out what the arguments do.
 
-If you need to do something more complicated, you can use `poetry run -- mike
+If you need to do something more complicated, you can use `uv run mike
 ...` commands. You can also edit the `gh-pages` bookmark directly, but take care
 to avoid files that will be overwritten by future invocations of `mike`. Then,
 you can submit a PR based on the `gh-pages` bookmark of

flake.nix

@@ -181,7 +181,7 @@
           openssh
 
           # For building the documentation website
-          poetry
+          uv
         ] ++ darwinDeps ++ linuxNativeDeps;
 
         shellHook = ''

mkdocs-offline.yml

@@ -1,6 +1,6 @@
 # This config is good if you plan to use the rendered docs from
 # your file system. To use, run:
-#      poetry run -- mkdocs build -f mkdocs-offline.yml
+#      uv run mkdocs build -f mkdocs-offline.yml
 INHERIT: 'mkdocs.yml'
 plugins:
     - offline