Skip to content

manual: bump mdbook to 0.5.x and replace mdbook-environment env-var interpolation #240

Description

@schell

Problem

manual/book.toml declares the [preprocessor.environment] preprocessor (the
mdbook-environment crate) to
interpolate {{DOCS_URL}} (and other env vars) into the manual's markdown.
mdbook-environment 0.0.4 (latest, built against mdbook ^0.4) cannot parse
mdbook 0.5's preprocessor input, so with mdbook 0.5.x the manual build fails:

INFO Book building has started
Unable to parse the input
ERROR The "environment" preprocessor exited unsuccessfully with exit status: 1

Because xtask's Manual::install_deps installs mdbook unpinned
(cargo install mdbook), a fresh machine now gets mdbook 0.5.x (latest 0.5.4)
and the manual cannot build. Downstream, the renderling.xyz site pipeline then
fails with a confusing manual/book canonicalize panic.

Workaround currently in place: the deploy machine is pinned to
mdbook 0.4.52 (cargo install mdbook --version 0.4.52 --force). The wgsl-rs
book (which uses no external preprocessors) builds fine on both 0.4 and 0.5.

Ask

  1. Bump to mdbook 0.5.x and replace the env-var interpolation with something
    that works there. Ideas: vendor/patch mdbook-environment against 0.5 (or
    upstream a fix), generate the docs URL into an {{#include}}d file at
    build time from xtask (which already receives --docs-url), or
    preprocess the sources before invoking mdbook.
  2. Pin the mdbook version in Manual::install_deps either way, so a fresh
    machine cannot silently drift onto an incompatible version.

Related

  • deps.rs has_binary probes for binaries by shelling out to hash, a shell
    builtin — a fragile check.
  • When the manual build fails, xtask logs could not build the manual but
    exits 0, so callers believe the build succeeded and fail later with an
    unrelated-looking panic. The build failure should exit non-zero.

Found while deploying the wgsl-rs operator's manual through the renderling.xyz
pipeline (wgsl-rs#29).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions