docs: migrate from poetry to uv

Our docs are built with MkDocs, which requires Python and several deps.

Previously those deps were managed with Poetry, which is also written in Python.
This commit replaces Poetry with `uv`, a Rust-based Python
project/package manager, and thus removes several steps from the docs
build process.

Before:

  <install Python>
  <install pipx>
  pipx install poetry
  poetry install
  poetry run -- mkdocs serve

After:

  <install uv>
  uv run mkdocs serve

.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

@@ -12,6 +12,10 @@ result
 # See https://insta.rs/docs/settings/#tool-config-file for details.
 .config/insta.yaml
 
+# mkdocs
+/.venv
+/.python-version
+
 # Editor specific ignores
 .idea
 .vscode

docs/contributing.md

@@ -277,33 +277,16 @@ result will look as expected when published to the website.
 
 ### Setting up the prerequisites
 
-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].
-
-[Python installation instructions]: https://docs.python.org/3/using/index.html
-[Poetry installation instructions]: https://python-poetry.org/docs/#installation
-
-Once you have `poetry` installed, you should ask it to install the rest
-of the required tools into a virtual environment as follows:
+To build the website, you must have `uv` installed (version 0.5.1 or later).
+Please see: [Installing uv].
 
-```shell
-poetry install
-```
+[Installing uv]: https://docs.astral.sh/uv/getting-started/installation/
 
-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:
+Once you have `uv` installed, you should ask it to install the rest
+of the required tools into a virtual environment as follows:
 
 ```shell
-# For sh-compatible shells or recent versions of `fish`
-export PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring
+uv sync
 ```
 
 ### Building the HTML docs locally (with live reload)
@@ -314,15 +297,15 @@ following the above steps, you should be able to view the docs by running
 ```shell
 # Note: this and all the commands below should be run from the root of
 # the `jj` source tree.
-poetry run -- mkdocs serve
+uv run mkdocs serve
 ```
 
 and opening <http://127.0.0.1:8000> in your browser.
 
 As you edit the `md` files, the website should be rebuilt and reloaded in your
 browser automatically, unless build errors occur.
 
-You should occasionally check the terminal from which you ran `mkdocs serve` for
+You should occasionally 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.
 
@@ -336,7 +319,7 @@ 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):
@@ -397,11 +380,11 @@ The script sets up the `site_url` mkdocs config to
 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