require poetry 1.8, recommend installing it via pipx

I feel like recommending people install Poetry via a package manager was
a mistake. Poetry only supports its latest version, and while newer
versions are sort-of backward-compatible, they print warnings in
different situations and have different bugs.  Installing `pipx` via a
package manager, OTOH, works fine, and its older versions work fine.

Using Poetry 1.8+ allows us to use Poetry's new "non-package" mode,
which would no longer print warnings if the user does `poetry install`
instead of `poetry install --no-root`. It's likely that in newer
versions of Poetry, it will become an error.

.github/scripts/docs-build-deploy

@@ -16,7 +16,7 @@ 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 --no-root # Only really needed once per environment unless there are updates
+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

.github/workflows/build.yml

@@ -109,17 +109,17 @@ jobs:
       - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
         with:
           python-version: 3.11
-      - name: Install poetry
+      - name: Install poetry (latest release)
         uses: abatilo/actions-poetry@7b6d33e44b4f08d7021a1dee3c044e9c253d6439
         with:
           poetry-version: latest
       - name: Install dependencies
-        run: poetry install --no-root
+        run: poetry install 
       - name: Check that `mkdocs` can build the docs
         run: poetry run -- mkdocs build --strict
 
   mkdocs-old-poetry:
-    name: Check that MkDocs can build the docs with Poetry 1.3.2
+    name: Check that MkDocs can build the docs with Poetry 1.8
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
@@ -135,9 +135,9 @@ jobs:
           #
           # One way to install old `poetry` is using `pipx`:
           #    pipx install 'poetry<1.4' --suffix -1.3
-          poetry-version: 1.3.2
+          poetry-version: 1.8
       - name: Install dependencies
-        run: poetry install --no-root
+        run: poetry install 
       - name: Check that `mkdocs` can build the docs
         run: poetry run -- mkdocs build --strict
 

.github/workflows/release.yml

@@ -106,7 +106,7 @@ jobs:
           poetry-version: latest
       - name: Compile docs and zip them up
         run: |
-          poetry install --no-root
+          poetry install 
           poetry run -- mkdocs build -f mkdocs-offline.yml
           archive="jj-${{ github.event.release.tag_name }}-docs-html.tar.gz"
           tar czf "$archive" -C "rendered-docs" .

docs/contributing.md

@@ -217,12 +217,13 @@ result will look as expected when published to the website.
 
 ### Setting up the prerequisites
 
-To build the website, you must have Python and `poetry` installed. If
-your distribution packages `poetry`, something like `apt install
-python3-poetry` is likely the best way to install it. Otherwise, you
-can download Python from <https://python.org> or follow the [Python
-installation instructions]. Finally, follow the [Poetry installation
-instructions].
+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 
@@ -231,16 +232,14 @@ Once you have `poetry` installed, you should ask it to install the rest
 of the required tools into a virtual environment as follows:
 
 ```shell
-# --no-root avoids a harmless error message starting with Poetry 1.7
-poetry install --no-root
+poetry install
 ```
 
 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, in the case of
-Poetry 1.7, it 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 --no-root` again:
+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
 # For sh-compatible shells or recent versions of `fish`

pyproject.toml

@@ -1,11 +1,8 @@
 # The `dev-dependencies` section sets up tools for building `jj`
 # documentation. `poetry` will install these in a virtual environment.
-# The other sections are unused.
 [tool.poetry]
 name = "jj-docs"
-version = "0"
-description = ""
-authors = []
+package-mode = false
 
 [tool.poetry.dependencies]
 python = "^3.8"
@@ -23,7 +20,3 @@ mdx-breakless-lists = "^1.0.1"
 mkdocs-redirects = "^1.2.1"
 # Used for the CLI reference
 mkdocs-include-markdown-plugin = "^6.0.4"
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"