docs: Added guide on debugging workflows#4029
Conversation
<!--Add a description of your PR here--> Added a docs page on debugging workflows: - log file locations - faster DAG resolution - interactive debugging ### QC <!-- Make sure that you can tick the boxes below. --> * [ ] The PR contains a test case for the changes or the changes are already covered by an existing test case. **Not applicable - only documentation affected** * [X] The documentation (`docs/`) is updated to reflect the changes or this is not necessary (e.g. if the change does neither modify the language nor the behavior or functionalities of Snakemake).
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a new documentation page on debugging Snakemake workflows and registers it in the docs index under "Defining workflows". The page documents log locations, per-job logs, STDERR redirection for scripts, R backtraces, DAG-targeted runs, VS Code debugging setup, breakpoints, and preserving wrapper scripts. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
<!--Add a description of your PR here--> Added section on preserving wrapper scripts ### QC <!-- Make sure that you can tick the boxes below. --> * [ ] The PR contains a test case for the changes or the changes are already covered by an existing test case. **Docs only** * [x] The documentation (`docs/`) is updated to reflect the changes or this is not necessary (e.g. if the change does neither modify the language nor the behavior or functionalities of Snakemake).
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/snakefiles/debugging_workflows.rst`:
- Line 77: Docs have small typos: remove the duplicated word "with" in the
sentence containing "Visual Studio Code <https://code.visualstudio.com/> editor
comes with with", remove the extra period in the phrase "variables.." (make it
"variables."), and replace the incorrect "library() s" token with "library()" or
"library() calls" for correct wording; update those three occurrences (the
fragments "with with", "variables..", and "library() s") accordingly in the
documentation.
- Around line 100-111: The VS Code launch snippet incorrectly sets "program":
"-m" and passes "snakemake" in the "args" list; update the launch configuration
to use "module": "snakemake" (remove the "program" entry) and remove "snakemake"
from the "args" array so the Snakemake module is launched via the "module"
field; ensure other args like "--debug", "--cores", "--nolock", "--forceall",
and "--executor" remain in "args" and keep "python":
"${command:python.interpreterPath}" as-is.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: bd277526-3cb0-4990-a784-f96bc2cd0cc8
📒 Files selected for processing (2)
docs/index.rstdocs/snakefiles/debugging_workflows.rst
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/snakefiles/debugging_workflows.rst (1)
150-150:⚠️ Potential issue | 🟡 MinorFix awkward phrasing: "library() s".
The phrasing "library() s" is awkward. Consider rephrasing to one of:
- "load all the libraries you need"
- "load all the
library()calls you need"- "call all the
library()functions you need"📝 Suggested fix
-Start an interactive R session and load all the ``library()`` s that you need for the script. Then you can load the full workspace and interactively explore / debug what's going on: +Start an interactive R session and load all the libraries you need for the script. Then you can load the full workspace and interactively explore / debug what's going on:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/snakefiles/debugging_workflows.rst` at line 150, The sentence "load all the ``library()`` s that you need" uses awkward spacing and pluralization; update the wording in docs/snakefiles/debugging_workflows.rst to a clearer phrase such as "load all the libraries you need", "call all the `library()` functions you need", or "load all the `library()` calls you need" and ensure the inline code formatting remains for `library()` where appropriate (reference symbol: library()).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/snakefiles/debugging_workflows.rst`:
- Line 150: The sentence "load all the ``library()`` s that you need" uses
awkward spacing and pluralization; update the wording in
docs/snakefiles/debugging_workflows.rst to a clearer phrase such as "load all
the libraries you need", "call all the `library()` functions you need", or "load
all the `library()` calls you need" and ensure the inline code formatting
remains for `library()` where appropriate (reference symbol: library()).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 520eef59-a74f-4692-959c-2ff796e0b822
📒 Files selected for processing (2)
docs/index.rstdocs/snakefiles/debugging_workflows.rst
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/index.rst
dlaehnemann
left a comment
There was a problem hiding this comment.
This looks good, thanks for taking the time to bring this together. I mostly have some minor suggestions, and on thing that will especially make further reviewing and editing easier:
We generally try to have one sentence per line. That way the diffs are easier to read.
But only apply that once you've gone through the suggestions, as they might otherwise not be rendered correctly any more...
Co-authored-by: David Laehnemann <1379875+dlaehnemann@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/snakefiles/debugging_workflows.rst`:
- Line 21: Replace the misspelled word "pluging" with "plugin" in the sentence
containing "documentation of the respective executor pluging" so the text reads
"documentation of the respective executor plugin"; update the sentence in
docs/snakefiles/debugging_workflows.rst (the line containing that phrase) to fix
the typo and resolve the Codespell failure.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 5a2e23b8-7794-408d-a012-0e68a232511d
📒 Files selected for processing (1)
docs/snakefiles/debugging_workflows.rst
|
Hi @dlaehnemann , thanks for the suggestions, included them.
Done! Added a (really minimal) example on the breakpoints as well. |
|
@dlaehnemann @mrmattuschka All points have been addressed, so this is ready to be merged? |
🤖 I have created a release *beep* *boop* --- ## [9.21.1](v9.21.0...v9.21.1) (2026-05-29) ### Bug Fixes * add default json function to benchmarks ([#4128](#4128)) ([41fab22](41fab22)) * do not rerun when checkpoint job missing but downstream file exists ([#4124](#4124)) ([a060b93](a060b93)) * ensure that error logs contain all available details ([#4183](#4183)) ([74a86e9](74a86e9)) * handle missing pss attribute in benchmark on Windows ([#4160](#4160)) ([da52080](da52080)) * implement Resources.setdefault ([#3968](#3968)) ([2413e99](2413e99)) * reporting remote nodes number ([#3978](#3978)) ([8c534f0](8c534f0)) * resolve pathvars before constructing storage queries ([#3969](#3969)) ([bd15237](bd15237)) * storage temp() file cleanup with RemoteProvider ([#4189](#4189)) ([898bad1](898bad1)) * tolerate FileNotFoundError in drop_iocache ([#4153](#4153)) ([#4191](#4191)) ([ce26b28](ce26b28)) ### Documentation * Added guide on debugging workflows ([#4029](#4029)) ([3d052ae](3d052ae)) * **cli:** Remove broken ref bold markup ([#4204](#4204)) ([1200ebf](1200ebf)) * remove duplicated resources attribute in rules.rst ([#4190](#4190)) ([6c8ecdd](6c8ecdd)) * **rules:** Update script type hint advice ([#4193](#4193)) ([6108712](6108712)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).
Closes #4013 .
Added a docs page on debugging workflows:
scriptrule wrapper scriptsQC
Not applicable - only documentation affected
docs/) is updated to reflect the changes or this is not necessary (e.g. if the change does neither modify the language nor the behavior or functionalities of Snakemake).Summary by CodeRabbit