docs: Rework tutorial#4068
Conversation
|
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:
📝 WalkthroughWalkthroughDocumentation edits across multiple tutorial pages (basics, advanced, additional_features, interaction_visualization_reporting, tutorial) plus a docs configuration change: HTML prev/next navigation enabled and a new public Sphinx role Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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 |
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 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/tutorial/additional_features.rst`:
- Line 68: Replace the typo "hany" with the correct word "many" in the benchmark
description sentence ("When a job derived from the rule is executed, Snakemake
will measure the wall clock time, memory usage (in MiB), and several other hany
metrics...") so the sentence reads "...and several other many metrics..."
(actually better: "...and several other metrics...") — update the sentence in
docs/tutorial/additional_features.rst to remove the misspelling.
- Around line 215-218: The example mixes wildcard names "sample" and "dataset",
causing confusion; update the text so it consistently uses one name (preferably
"sample") throughout: change occurrences of `dataset="A.1"` and `dataset="A"` to
`sample="A.1"` and `sample="A"`, and keep the constraint example as
`{sample,[A-Z]+}.{group}` while referring to the output file
`{sample}.{group}.txt` and target `A.1.normal.txt` to ensure the wildcard name
is consistent.
- Around line 3-4: The section adornments (underlines) are too short for their
headings — e.g., the "Additional Features: Benchmarking, Modularization" heading
— causing reStructuredText "Title underline too short" warnings; update each
offending underline so its length matches or exceeds the length of the
corresponding heading text (extend the underline characters '-' or '=' to at
least the same number of characters as the heading) for the three sections
flagged so the document parses correctly.
In `@docs/tutorial/advanced.rst`:
- Around line 3-4: The top-level heading "Advanced: Configuration, Input
Functions, Logging" has an underline that's too short; update the underline
under that heading so it matches the heading length (repeat '-' to equal the
title's 49 characters) so the reStructuredText title underline is the same
length as the heading text.
In `@docs/tutorial/basics.rst`:
- Around line 96-103: The opening sentence "In Snakemake workflows are
defined..." is ungrammatical; update the first sentence to a concise,
grammatically correct form such as "In Snakemake, workflows are defined by
specifying rules in a ``Snakefile``." Also tighten surrounding wording for
clarity while preserving the mentions of rule names and directives (``rule``,
``Snakefile``, ``input``, ``output``, ``shell``) and ensure punctuation (commas
and backticks) is correct.
In `@docs/tutorial/tutorial.rst`:
- Around line 3-5: The title adornments for "Tutorial: A Basic Workflow" are too
short and cause an rst build warning; update both the overline and underline
surrounding the heading (the two lines of equals signs currently of length 21)
to match the heading length of 26 characters so both line 3 and line 5 use 26
equals signs each.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 547c453d-1972-4fa8-ad48-e03c926349d2
📒 Files selected for processing (6)
docs/conf.pydocs/tutorial/additional_features.rstdocs/tutorial/advanced.rstdocs/tutorial/basics.rstdocs/tutorial/interaction_visualization_reporting/tutorial.rstdocs/tutorial/tutorial.rst
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/tutorial/tutorial.rst (1)
9-20:⚠️ Potential issue | 🔴 CriticalRestore missing hyperlink targets to fix Sphinx build failure.
At Line 9 onward, references like
Snakemake_,GNU Make_,Python_,Conda_, andSingularity_are used, but their targets are missing in this file. This matches the docs pipeline error and blocks the build.🔧 Proposed fix
.. _slides: https://slides.com/johanneskoester/snakemake-tutorial +.. _Snakemake: https://snakemake.readthedocs.io +.. _GNU Make: https://www.gnu.org/software/make +.. _Python: https://www.python.org +.. _Conda: https://conda.io +.. _Singularity: https://sylabs.io/docs/🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/tutorial/tutorial.rst` around lines 9 - 20, The referenced inline targets (Snakemake_, GNU Make`_, Python_, Conda_, Singularity_) are missing and causing the Sphinx build to fail; add explicit hyperlink targets for each reference (e.g., add reST target definitions for Snakemake_, GNU Make_, Python_, Conda_, and Singularity_) pointing to the correct external URLs and place them in this document (typically at the end or top of tutorial.rst) so the references resolve during the docs build; ensure the target names exactly match the reference tokens (including the trailing underscore) used in the text.
🤖 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/conf.py`:
- Around line 317-321: The function oldheading_role uses mutable default args
options={} and content=[] which can leak state; change the signature to use
options=None and content=None, then inside oldheading_role set options = {} if
options is None and content = [] if content is None before calling anchor_role,
preserving the same call to anchor_role(name, rawtext, anchor_id, lineno,
inliner, options=options, content=content).
In `@docs/tutorial/basics.rst`:
- Around line 142-145: Replace the incorrect wording instances in the tutorial:
change the phrase "re-runs" to "re-run" where it appears in the sentence
"Snakemake will **only** re-runs jobs..." (search for the token "re-runs"), and
fix the typo "thefollowing" to "the following" (search for the token
"thefollowing") so the text reads correctly in both places.
---
Outside diff comments:
In `@docs/tutorial/tutorial.rst`:
- Around line 9-20: The referenced inline targets (Snakemake_, GNU Make`_,
Python_, Conda_, Singularity_) are missing and causing the Sphinx build to fail;
add explicit hyperlink targets for each reference (e.g., add reST target
definitions for Snakemake_, GNU Make_, Python_, Conda_, and Singularity_)
pointing to the correct external URLs and place them in this document (typically
at the end or top of tutorial.rst) so the references resolve during the docs
build; ensure the target names exactly match the reference tokens (including the
trailing underscore) used in the text.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 235350ee-3ac6-4d1e-bc80-2db89ed3e5b1
⛔ Files ignored due to path filters (1)
docs/gurobi.logis excluded by!**/*.log
📒 Files selected for processing (6)
docs/conf.pydocs/tutorial/additional_features.rstdocs/tutorial/advanced.rstdocs/tutorial/basics.rstdocs/tutorial/interaction_visualization_reporting/tutorial.rstdocs/tutorial/tutorial.rst
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/tutorial/interaction_visualization_reporting/tutorial.rst
- docs/tutorial/advanced.rst
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/tutorial/basics.rst (1)
481-482: Optional: Remove comma for smoother sentence flow.The comma after
plots/quals.svgslightly interrupts the sentence flow. Removing it would make the sentence read more naturally.✏️ Proposed wording
-the execution plan for creating the file ``plots/quals.svg``, will be shown. +the execution plan for creating the file ``plots/quals.svg`` will be shown.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/tutorial/basics.rst` around lines 481 - 482, Remove the comma following the quoted file path in the sentence containing "the execution plan for creating the file ``plots/quals.svg``" so the phrase reads smoothly; edit the sentence that currently reads "the execution plan for creating the file ``plots/quals.svg`, will be shown." to remove the comma after ``plots/quals.svg`` and ensure spacing and punctuation remain correct.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/tutorial/basics.rst`:
- Around line 481-482: Remove the comma following the quoted file path in the
sentence containing "the execution plan for creating the file
``plots/quals.svg``" so the phrase reads smoothly; edit the sentence that
currently reads "the execution plan for creating the file ``plots/quals.svg`,
will be shown." to remove the comma after ``plots/quals.svg`` and ensure spacing
and punctuation remain correct.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 9da39508-baef-439f-ac17-6a1996c20780
📒 Files selected for processing (2)
docs/tutorial/basics.rstdocs/tutorial/interaction_visualization_reporting/tutorial.rst
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/tutorial/interaction_visualization_reporting/tutorial.rst
|
The remaining failure was unrelated and due to http issues. |
|
Thanks a lot, great work! |
🤖 I have created a release *beep* *boop* --- ## [9.17.3](v9.17.2...v9.17.3) (2026-03-24) ### Bug Fixes * add curl when containerize with wrapper ([#4115](#4115)) ([44979e4](44979e4)) * ensure proper wrapper prefix is passed to CWL and shown in wrapper error messages ([#4121](#4121)) ([11b6f29](11b6f29)) * ensure that strings that purely contain integers or floats (e.g. "42") remain strings when parsing profiles ([#4119](#4119)) ([3ca08e1](3ca08e1)) * incorrect highlighting in HTML report ([#4120](#4120)) ([1ef224d](1ef224d)) ### Documentation * document an accidental (sorry) recent breaking change in type checking compatibility of Python scripts, in favor of a clean and robust new syntax ([#4116](#4116)) ([013bc43](013bc43)) * Rework tutorial ([#4068](#4068)) ([4bba4a9](4bba4a9)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Chores** * Released version 9.17.3 <!-- end of auto-generated comment: release notes by coderabbit.ai -->
Notes
Going through the tutorial, I was a bit unsure about the config / input function section, because it doesn't seem very useful for this specific task?
Snakemake was able to infer the path for each sample just fine in the previous step, and the 'improved' solution with input functions / config then actually requires the user to provide a complete path for each sample in the config again, as far as I understand. Am I missing something here, or can we maybe think of a more useful input function as an example?
QC
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