Website (poetry and mike)-related updates

.github/scripts/docs-build-deploy

@@ -9,9 +9,14 @@
 set -ev
 
 export "SITE_URL_FOR_MKDOCS=$1"; shift
-# https://github.com/python-poetry/poetry/issues/1917
+# Affects the generation of `sitemap.xml.gz` by `mkdocs`. See
+# 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
+poetry install --no-root # Only really needed once per environment unless there are updates
 # TODO(ilyagr): The new default "alias-type" is symlink, we should consider
 # switching to it.
 poetry run -- mike deploy --alias-type redirect "$@"

.github/workflows/build.yml

@@ -75,7 +75,27 @@ jobs:
         with:
           poetry-version: latest
       - name: Install dependencies
-        run: poetry install
+        run: poetry install --no-root
+      - 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
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - name: Install poetry
+        uses: abatilo/actions-poetry@v2
+        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.
+          poetry-version: 1.3.2
+      - name: Install dependencies
+        run: poetry install --no-root
       - name: Check that `mkdocs` can build the docs
         run: poetry run -- mkdocs build --strict
 

.github/workflows/release.yml

@@ -91,7 +91,7 @@ jobs:
           poetry-version: latest
       - name: Compile docs and zip them up
         run: |
-          poetry install
+          poetry install --no-root
           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

@@ -184,13 +184,16 @@ Once you have `poetry` installed, you should ask it to install the rest
 of the required tools into a virtual environment as follows:
 
 ```shell
-poetry install
+# --no-root avoids a harmless error message starting with Poetry 1.7
+poetry install --no-root
 ```
 
-If you get requests to "unlock a keyring" or error messages about failing to do
-so, this is a [known `poetry`
-bug](https://github.com/python-poetry/poetry/issues/1917). The workaround is to
-run the following and then to try `poetry install` again:
+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:
 
 ```shell
 # For sh-compatible shells or recent versions of `fish`

pyproject.toml

@@ -10,7 +10,7 @@ authors = []
 [tool.poetry.dependencies]
 python = "^3.8"
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 # These can be updated with `poetry add`.
 mkdocs = "^1.5.2"
 mkdocs-material = "^9.4"