Skip to content

docs: make the permutation_init doctests deterministic (drop the duplicate docs workflow) - #542

Merged
ChrisRackauckas merged 3 commits into
SciML:masterfrom
ChrisRackauckas-Claude:docs/fix-doctests-and-ci
Sep 22, 2026
Merged

ChrisRackauckas merged 3 commits into
SciML:masterfrom
ChrisRackauckas-Claude:docs/fix-doctests-and-ci

Conversation

@ChrisRackauckas-Claude

@ChrisRackauckas-Claude ChrisRackauckas-Claude commented Sep 17, 2026 •

Copy link
Copy Markdown
Member

Please ignore until reviewed by @ChrisRackauckas.

What changed and why

permutation_init returns a randomly permuted matrix, but two jldoctest blocks in the permutation_init docstring printed that matrix, so the expected output depended on the draw. They now assert the structure instead:

julia> m = permutation_init(5, 5);

julia> size(m) == (5, 5) && count(!iszero, m) == 5 && sort(vec(m[m .!= 0])) == fill(0.1f0, 5)
true

Correction: an earlier revision of this PR also added a .github/workflows/Documentation.yml built on ubuntu-latest. That was wrong and has been removed. ReservoirComputing already builds its documentation on a self-hosted GPU runner — the gpu-docs job in .github/workflows/GPU.yml, whose workflow is literally named "GPU Documentation", runs-on: [self-hosted, Linux, X64, gpu] — and that job is green on master, so there was no docs build to repair.

Verification

  • master's GPU docs job is green: run https://github.com/SciML/ReservoirComputing.jl/actions/runs/35146312301 → Documentation=success.
  • The two rewritten doctests are deterministic: the assertion checks shape, the number of nonzeros and the sorted nonzero values, none of which depend on the permutation.
  • grep -rl 'docs/make.jl' .github/workflows matches only GPU.yml after this change.

Not verified

  • The GPU docs job on this branch (draft PRs skip it); the doctest content change itself is covered by the existing green GPU build.
  • Whether the RNG dependence was causing visible flakiness in CI; it is a latent flake that this removes.

🤖 Generated with OpenCode (model: muse-spark-1.3-contributor-free); no public session URL (local session at /home/crackauc/sandbox/tmp_20260917_040834_91074).

This repo had complete docs sources but no docs CI. Standard
reusable workflow call including the token permissions the reusable
requires.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Agent-Harness: OpenCode
Agent-Model: muse-spark-1.3-contributor-free
Agent-Session: local session at /home/crackauc/sandbox/tmp_20260917_040834_91074 (no public conversation URL)
@ChrisRackauckas
ChrisRackauckas marked this pull request as ready for review September 17, 2026 18:03
These doctests printed random permutations, passing only by luck of
global RNG state (explicit seeds still differ across environments
for this call path). Assert shape, nonzero count, and value
multiset instead, matching the style of the adjacent weights
example. Verified: full local docs build passes with 0 failures.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Agent-Harness: OpenCode
Agent-Model: muse-spark-1.3-contributor-free
Agent-Session: local session at /home/crackauc/sandbox/tmp_20260917_040834_91074 (no public conversation URL)
ReservoirComputing already builds its documentation on a self-hosted GPU
runner: the `gpu-docs` job in `.github/workflows/GPU.yml`, whose workflow is
literally named "GPU Documentation", `runs-on: [self-hosted, Linux, X64, gpu]`.
That job is green on master, so there is no docs build to repair and a second
workflow on `ubuntu-latest` would only deploy the same site twice.

Keep the deterministic-doctest fix: `permutation_init` returns a randomly
permuted matrix and the old `jldoctest` printed it, so the expected output
depended on the draw.

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Agent-Harness: OpenCode
Agent-Model: muse-spark-1.3-contributor-free
Agent-Session: local session at /home/crackauc/sandbox/tmp_20260917_040834_91074 (no public conversation URL)
@ChrisRackauckas-Claude ChrisRackauckas-Claude changed the title docs: add docs CI and seed RNG in permutation_init doctests docs: make the permutation_init doctests deterministic (drop the duplicate docs workflow) Sep 19, 2026
@ChrisRackauckas
ChrisRackauckas merged commit 9686fe5 into SciML:master Sep 22, 2026
43 of 57 checks passed
ChrisRackauckas added a commit that referenced this pull request Sep 23, 2026
Ships the deterministic permutation_init doctests and the removal of the duplicate docs workflow (#542).

Co-Authored-By: Chris Rackauckas <accounts@chrisrackauckas.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Agent-Harness: Claude Code 2.1.273
Agent-Model: claude-opus-5[1m]
Agent-Session: 6a01e420-3436-4518-83cc-6cd853283cfb (local transcript; this harness publishes no conversation URL)
ChrisRackauckas added a commit that referenced this pull request Sep 23, 2026
Ships the deterministic permutation_init doctests and the removal of the duplicate docs workflow (#542).



Agent-Harness: Claude Code 2.1.273
Agent-Model: claude-opus-5[1m]
Agent-Session: 6a01e420-3436-4518-83cc-6cd853283cfb (local transcript; this harness publishes no conversation URL)

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants