glm-5.3-flash
f215748f7b
- new scripts/docs-check.sh, the pre-publish docs gate: rustdoc build with -D warnings (broken intra-doc links and doc lints fail locally, docs.rs does not fail on warnings, so this is stricter than production), doctests in both feature configurations with a hard zero-ignored-assertion (ignored = uncompiled = untested, convention 16), and a badge scan over the rendered HTML for the stable 'example-wrap ignore' markup class (tooltip wording varies across rustdoc versions, the class does not) - verified both directions: green on the current tree; a temporary scratch ignore block fails the gate at the doctests step - Cargo.toml exclude gains scripts/ so the helper never ships in the package; AGENTS.md verification commands and convention 16 reference the gate
54 lines
2.2 KiB
Bash
Executable File
54 lines
2.2 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# Docs sanity gate: run before a publish (AGENTS.md convention 16).
|
|
# Catches what `cargo doc` alone does not: ignore-marked doc examples,
|
|
# which rustdoc renders with the untested badge that docs.rs surfaces on
|
|
# the crate page (the tooltip "This example is not tested"; the wording
|
|
# varies by rustdoc version, so we grep the stable `example-wrap ignore`
|
|
# markup class instead).
|
|
#
|
|
# 1. rustdoc build with warnings as errors: broken intra-doc links,
|
|
# broken anchors, and doc lints fail here instead of surfacing on
|
|
# docs.rs (docs.rs does not fail on warnings, so the local gate is
|
|
# stricter than production).
|
|
# 2. doctests in both feature configurations, with the rule that zero
|
|
# doctests are ignored (ignored = uncompiled = untested). The lib
|
|
# doctest count is expected: 1 compiled (the assembly example), 0
|
|
# ignored. Feature-gated example bodies compile as empty under
|
|
# default features and fully under --all-features.
|
|
# 3. badge scan over the rendered HTML: no `example-wrap ignore` markup
|
|
# and no "example is ... tested" tooltip text anywhere in target/doc.
|
|
set -euo pipefail
|
|
root="$(git rev-parse --show-toplevel)"
|
|
cd "$root"
|
|
|
|
echo "== rustdoc build, warnings as errors (default features)"
|
|
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
|
|
|
|
ignored_count() {
|
|
echo "$1" | grep -o '[0-9]* ignored' | awk '{s += $1} END {print s + 0}'
|
|
}
|
|
|
|
for cfg in "" "--all-features"; do
|
|
label="default features"
|
|
[ -n "$cfg" ] && label="--all-features"
|
|
echo "== doctests ($label)"
|
|
out="$(cargo test --doc $cfg 2>&1)"
|
|
echo "$out" | grep -E '^test result' | sed "s/^/ $label: /"
|
|
ignored="$(ignored_count "$out")"
|
|
if [ "$ignored" != "0" ]; then
|
|
echo "FAIL: $ignored ignored doctest(s) ($label); convention 16:" \
|
|
"examples are tested or no_run, never ignore" >&2
|
|
exit 1
|
|
fi
|
|
done
|
|
|
|
echo "== untested-badge scan over target/doc"
|
|
badges="$(grep -rlE 'example-wrap[ "]?ignore|This example is (not |un)?tested' \
|
|
target/doc/alktty/*.html 2>/dev/null || true)"
|
|
if [ -n "$badges" ]; then
|
|
echo "FAIL: untested-documentation badge(s) in the rendered docs:" >&2
|
|
echo "$badges" | sed 's/^/ /' >&2
|
|
exit 1
|
|
fi
|
|
|
|
echo "docs-check: ok" |