Add deprecated warnings to the legacy build and deploy sphinx workflows

[Pierre Siddall (Pierre-siddall)]

PR Summary

Code Reviewer: Yaswant Pradhan (@yaswant)

This PR adds a deprecated warning to a couple of legacy workflows to ensure that users migrate to the sphinx-docs.yaml workflow.

✅ Code Quality Checklist

(Some checks are automatically carried out via the CI pipeline)

• I have performed a self-review of my own code
• My code follows the project's style guidelines
• The modified workflow's README has been updated, if required
• The changes have been sufficiently tested (please describe)

🤖 AI Assistance and Attribution

• Some of the content of this change has been produced with the assistance of Generative AI tool name (e.g., Met Office GitHub Copilot Enterprise, GitHub Copilot Personal, ChatGPT GPT-4, etc) and I have followed the Simulation Systems AI policy (including attribution labels)

💻 Code Review

• The changes are appropriate and testing has been sufficient

[Copilot]

Pull request overview

This PR adds explicit GitHub Actions log warnings to two legacy, reusable Sphinx documentation workflows to encourage migration to the newer sphinx-docs.yaml workflow.

Changes:

• Added a “Deprecation warning” step at the start of the legacy build workflow.
• Added a “Deprecation warning” step at the start of the legacy deploy workflow.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
.github/workflows/build-sphinx-docs.yaml	Emits a ::warning at runtime to flag the reusable workflow as deprecated and direct users to sphinx-docs.yaml.
.github/workflows/deploy-sphinx-docs.yaml	Emits a ::warning at runtime to flag the reusable workflow as deprecated and direct users to sphinx-docs.yaml.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Yaswant Pradhan (yaswant)]

Thanks Pierre Siddall (@Pierre-siddall) It will be useful to provide an alert box to in the main execution summary page. I've some suggestion in your changed files, you can replicate that across.

I notice you have ticked AI assistance question. Can you please include details?

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

.github/workflows/build-sphinx-docs.yaml:68

• The step summary refers to a “new unified action”, but the migration target is a reusable workflow (.github/workflows/sphinx-docs.yaml). Using “workflow” here avoids confusing users.

          echo "> **Migration Path:** Please transition your workflows to use the new unified action instead. Refer to the [sphinx-docs workflow guide](https://github.com/MetOffice/growss/tree/main/sphinx-docs) for details." >> $GITHUB_STEP_SUMMARY

.github/workflows/build-sphinx-docs.yaml:63

• Deprecation warning text has a grammatical issue (missing article) and is slightly inconsistent with the other workflow’s phrasing. Consider using “in a future release” and “the sphinx-docs.yaml workflow” for clarity.

This issue also appears on line 68 of the same file.

          echo "::warning title=Workflow Deprecated::This reusable workflow will be removed in future release. Please migrate to sphinx-docs.yaml workflow."

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (4)

.github/workflows/deploy-sphinx-docs.yaml:44

• The deprecation summary uses unquoted $GITHUB_STEP_SUMMARY (safer to quote) and says "next release" which is a stronger promise than the "future release" warning above. Suggest aligning to "a future release" and quoting the variable.

          echo "### ⚠️ Deprecation Notice" >> $GITHUB_STEP_SUMMARY
          echo "The \`deploy-sphinx-docs\` reusable workflow has been **deprecated** and will be removed in the next release." >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "> **Migration Path:** Please transition your workflows to use the new unified action instead. Refer to the [sphinx-docs workflow guide](https://github.com/MetOffice/growss/tree/main/sphinx-docs) for details." >> $GITHUB_STEP_SUMMARY

.github/workflows/build-sphinx-docs.yaml:68

• The deprecation summary uses unquoted $GITHUB_STEP_SUMMARY (safer to quote) and says "next release" which is a stronger promise than the "future release" warning above. Suggest aligning to "a future release" and quoting the variable.

          echo "### ⚠️ Deprecation Notice" >> $GITHUB_STEP_SUMMARY
          echo "The \`build-sphinx-docs\` reusable workflow has been **deprecated** and will be removed in the next release." >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "> **Migration Path:** Please transition your workflows to use the new unified action instead. Refer to the [sphinx-docs workflow guide](https://github.com/MetOffice/growss/tree/main/sphinx-docs) for details." >> $GITHUB_STEP_SUMMARY

.github/workflows/deploy-sphinx-docs.yaml:39

• Grammar in the workflow warning message is off ("removed in future release") and the phrasing is slightly unclear. Consider using "removed in a future release" and adding "the" before the target workflow name so the warning reads cleanly.

This issue also appears on line 41 of the same file.

          echo "::warning title=Workflow Deprecated::This reusable workflow will be removed in future release. Please migrate to sphinx-docs.yaml workflow."

.github/workflows/build-sphinx-docs.yaml:63

• Grammar in the workflow warning message is off ("removed in future release") and the phrasing is slightly unclear. Consider using "removed in a future release" and adding "the" before the target workflow name so the warning reads cleanly.

This issue also appears on line 65 of the same file.

          echo "::warning title=Workflow Deprecated::This reusable workflow will be removed in future release. Please migrate to sphinx-docs.yaml workflow."

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (4)

.github/workflows/build-sphinx-docs.yaml:69

• Shell variable expansion should be quoted when redirecting, and the warning message is missing an article (“in a future release”).

          echo "::warning title=Workflow Deprecated::This reusable workflow will be removed in future release. Please migrate to sphinx-docs.yaml workflow."

          echo "### ⚠️ Deprecation Notice" >> $GITHUB_STEP_SUMMARY
          echo "The \`build-sphinx-docs\` reusable workflow has been **deprecated** and will be removed in the next release." >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

.github/workflows/deploy-sphinx-docs.yaml:45

• Shell variable expansion should be quoted when redirecting, and the warning message is missing an article (“in a future release”).

          echo "::warning title=Workflow Deprecated::This reusable workflow will be removed in future release. Please migrate to sphinx-docs.yaml workflow."

          echo "### ⚠️ Deprecation Notice" >> $GITHUB_STEP_SUMMARY
          echo "The \`deploy-sphinx-docs\` reusable workflow has been **deprecated** and will be removed in the next release." >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

.github/workflows/deploy-sphinx-docs.yaml:7

• There’s an extra trailing quote character in this AI-attribution comment, which reads like a typo and should be removed.

This issue also appears on line 41 of the same file.

# Some of the content of this file has been produced with the assistance of
# Claude Opus 4.8."

.github/workflows/build-sphinx-docs.yaml:7

• There’s an extra trailing quote character in this AI-attribution comment, which reads like a typo and should be removed.

This issue also appears on line 65 of the same file.

# Some of the content of this file has been produced with the assistance of
# Claude Opus 4.8."

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.github/workflows/deploy-sphinx-docs.yaml:46

• The deprecation notice text is internally inconsistent ("future release" vs "next release"), has a grammatical issue (missing "a"), and refers to a "unified action" even though the migration target is a workflow. Also, appending to $GITHUB_STEP_SUMMARY should be quoted to avoid shell word-splitting. Consider emitting the summary via a heredoc for readability and correctness.

          echo "::warning title=Workflow Deprecated::This reusable workflow will be removed in future release. Please migrate to sphinx-docs.yaml workflow."

          echo "### ⚠️ Deprecation Notice" >> $GITHUB_STEP_SUMMARY
          echo "The \`deploy-sphinx-docs\` reusable workflow has been **deprecated** and will be removed in the next release." >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

.github/workflows/build-sphinx-docs.yaml:70

• The deprecation notice text is internally inconsistent ("future release" vs "next release"), has a grammatical issue (missing "a"), and refers to a "unified action" even though the migration target is a workflow. Also, appending to $GITHUB_STEP_SUMMARY should be quoted to avoid shell word-splitting. Consider emitting the summary via a heredoc for readability and correctness.

          echo "::warning title=Workflow Deprecated::This reusable workflow will be removed in future release. Please migrate to sphinx-docs.yaml workflow."

          echo "### ⚠️ Deprecation Notice" >> $GITHUB_STEP_SUMMARY
          echo "The \`build-sphinx-docs\` reusable workflow has been **deprecated** and will be removed in the next release." >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (3)

.github/workflows/build-sphinx-docs.yaml:70

• This summary text says “new unified action”, but the migration target is a reusable workflow (sphinx-docs.yaml). Also, elsewhere in this repo the step summary path is quoted (e.g., .github/workflows/sphinx-docs.yaml uses cat >> "$GITHUB_STEP_SUMMARY"); quoting here avoids issues if the path contains spaces.

          echo "### ⚠️ Deprecation Notice" >> $GITHUB_STEP_SUMMARY
          echo "The \`build-sphinx-docs\` reusable workflow has been **deprecated** and will be removed in the next release." >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "> **Migration Path:** Please transition your workflows to use the new unified action instead. Refer to the [sphinx-docs workflow guide](https://github.com/MetOffice/growss/tree/main/sphinx-docs) for details." >> $GITHUB_STEP_SUMMARY

.github/workflows/deploy-sphinx-docs.yaml:46

• This summary text says “new unified action”, but the migration target is a reusable workflow (sphinx-docs.yaml). Also, elsewhere in this repo the step summary path is quoted (e.g., .github/workflows/sphinx-docs.yaml uses cat >> "$GITHUB_STEP_SUMMARY"); quoting here avoids issues if the path contains spaces.

          echo "### ⚠️ Deprecation Notice" >> $GITHUB_STEP_SUMMARY
          echo "The \`deploy-sphinx-docs\` reusable workflow has been **deprecated** and will be removed in the next release." >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "> **Migration Path:** Please transition your workflows to use the new unified action instead. Refer to the [sphinx-docs workflow guide](https://github.com/MetOffice/growss/tree/main/sphinx-docs) for details." >> $GITHUB_STEP_SUMMARY

.github/workflows/build-sphinx-docs.yaml:65

• The deprecation warning string is missing an article (“in the next release”), which reads awkwardly in logs and warnings.

This issue also appears on line 67 of the same file.

          echo "::warning title=Workflow Deprecated::This reusable workflow will be removed in next release. Please migrate to sphinx-docs.yaml workflow."