Skip to content

Conversation

@ChrisRackauckas-Claude
Copy link

Summary

This PR adds a GitHub Actions workflow to automatically build and deploy documentation on:

  • Pushes to master branch
  • Tagged releases

Problem

Issue #439 reported that the "Adding Parameters" tutorial example fails because the documentation website shows outdated syntax. Investigation revealed:

  1. The fix is already in master since Sept 8, 2024 (commit 9c77d49)
  2. The fix is included in v0.11.6 (released Oct 12, 2024)
  3. However, the stable symlink on gh-pages still points to v0.10.4 (Dec 2023)
  4. The docs were never rebuilt for any v0.11.x release

This means users visiting https://docs.sciml.ai/MethodOfLines/stable/tutorials/params/ see outdated documentation that uses the old (now broken) syntax:

# Old broken syntax shown on website
@named pdesys = PDESystem(eqs,bcs,domains,[t,x],[u(t,x),v(t,x)],[Dn=>0.5, Dp=>2])

Instead of the correct syntax that's in the master branch:

# Correct syntax in master
@named pdesys = PDESystem(
    eqs, bcs, domains, [t, x], [u(t, x), v(t, x)],
    [Dn, Dp]; defaults = Dict(Dn => 0.5, Dp => 2.0))

Solution

Adding a Documentation.yml workflow will:

  1. Automatically rebuild docs on pushes to master (updating dev/ docs)
  2. Automatically rebuild docs on tagged releases (updating stable symlink)

This ensures documentation stays in sync with code changes.

Test plan

  • Verify workflow runs successfully on PR (builds docs without errors)
  • After merge, verify dev/ docs are updated
  • On next release, verify stable symlink is updated

Closes #439

cc @ChrisRackauckas


🤖 Generated with Claude Code

ChrisRackauckas and others added 3 commits December 29, 2025 15:25
This adds a GitHub Actions workflow to build and deploy documentation
automatically on pushes to master and tagged releases.

The stable docs were pointing to v0.10.4 (Dec 2023) instead of the
latest v0.11.x releases, meaning fixes like the corrected PDESystem
parameter syntax were not reflected on the docs website.

Closes SciML#439

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add submodules: false to checkout action to avoid phantom submodule
entry for IRKGaussLegendre.jl that was causing CI failures.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Switch to the SciML/.github reusable workflow for documentation building.
This ensures consistency with other SciML packages and avoids custom
configuration issues.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ChrisRackauckas-Claude
Copy link
Author

The Documentation workflow is failing during the 'Build and Deploy Documentation' step. This could be due to:

  1. Documentation examples failing - The examples in the docs may still be using deprecated syntax somewhere
  2. DOCUMENTER_KEY authentication - On PRs, Documenter skips deployment but may still fail on auth
  3. Cache issues - The cache service returned 400 errors

The important finding from this investigation is that the documentation source has already been fixed in master (commit 9c77d49 from Sep 2024), but the published docs website still points to v0.10.4 which predates the fix.

The workflow itself is standard SciML reusable workflow. The real issue may need manual intervention to:

  1. Run the documentation build locally and verify it passes
  2. Trigger a tagged release which should update the stable symlink
  3. Or manually update the gh-pages stable symlink to point to a newer version

@ChrisRackauckas - Let me know if you'd like me to investigate the documentation build failure further or if a manual docs rebuild would be preferred.

@ChrisRackauckas ChrisRackauckas merged commit 34f3dc4 into SciML:master Dec 30, 2025
54 of 66 checks passed
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.

"Adding Parameters" tutorial example fails

2 participants