jj/.github/scripts/docs-build-deploy
Ilya Grigoriev 92403d7d11 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.
2024-05-27 10:53:35 -07:00

27 lines
1.6 KiB
Bash
Executable file

#!/bin/sh
# Set up a virtual environment with the required tools, build, and deploy the docs.
#
# 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`
# creates a commit directly on the `gh-pages` branch.
set -ev
export "SITE_URL_FOR_MKDOCS=$1"; shift
# 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
# 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 "$@"