Skip to content

docs: Rework tutorial#4068

Merged
johanneskoester merged 9 commits intosnakemake:mainfrom
schnea:clean-tutorial-docs
Mar 17, 2026
Merged

docs: Rework tutorial#4068
johanneskoester merged 9 commits intosnakemake:mainfrom
schnea:clean-tutorial-docs

Conversation

@schnea
Copy link
Copy Markdown
Contributor

@schnea schnea commented Mar 12, 2026

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

  • The PR contains a test case for the changes or the changes are already covered by an existing test case.
  • 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).

Summary by CodeRabbit

  • Documentation
    • Enabled previous/next navigation links for easier browsing
    • Restructured and retitled tutorial and guide sections for clearer, task-oriented flow
    • Major rewrites across basics, advanced, and additional-features tutorials with clearer examples and stepwise guidance
    • Expanded benchmarking, modularization (working with multiple Snakefiles), Conda/isolation, wrapper, and wildcard-constraint guidance
    • Fixed formatting, punctuation, and end-of-file rendering for consistency
    • Added a legacy heading alias to improve anchor compatibility in docs

@schnea schnea requested a review from dlaehnemann March 12, 2026 10:15
@schnea schnea requested a review from johanneskoester as a code owner March 12, 2026 10:15
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Mar 12, 2026

Note

Reviews paused

It 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 reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Documentation 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 oldheading added and registered in docs/conf.py.

Changes

Cohort / File(s) Summary
Configuration
docs/conf.py
Enable HTML previous/next navigation (show_prev_next = True) and add a new public Sphinx role oldheading via app.add_role("oldheading", oldheading_role); implemented oldheading_role(...).
Top-level tutorial index
docs/tutorial/tutorial.rst
Introductory rewrite: removed several external anchors, added a brief intro paragraph, lowered toctree maxdepth to 1, and expanded toctree targets to include additional pages.
Basics tutorial
docs/tutorial/basics.rst
Broad editorial restructure and rewrite: renamed steps/anchors, reorganized narrative and examples, clarified wildcard/expand behavior and script integration; content-only changes (no code/API).
Advanced tutorial
docs/tutorial/advanced.rst
Editorial refinements and reflow: capitalization and wording changes across steps, note repositioning, and minor formatting adjustments.
Additional features
docs/tutorial/additional_features.rst
Section renames and rewording, expanded benchmarking descriptions, clarified modularization/include usage and per-rule Conda guidance, updated wrapper example version to v8.1.1, and multiple formatting/text fixes.
Interaction/Visualization/Reporting tutorial
docs/tutorial/interaction_visualization_reporting/tutorial.rst
Shortened page title and removed leading blank lines from code blocks (formatting-only edits).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title 'docs: Rework tutorial' is directly related to the main changeset, which involves substantial rewrites and reorganization of tutorial documentation files across multiple sections.
Description check ✅ Passed The PR description references the linked issues, explains the key changes (reworded headers, added navigation, applied docs guidelines), and includes QC checklist confirmation that documentation was updated. However, the AI-assistance disclosure section is incomplete with no checkboxes marked.
Linked Issues check ✅ Passed The PR description mentions closing issues #184, #2008, #2442, #2387. Issue #184 requires updating the wrapper example from 0.15.3/bio/bwa/mem to a current version. The raw summary shows the wrapper version was updated from v6.2.0 to v8.1.1 in docs/tutorial/additional_features.rst, addressing the core requirement.
Out of Scope Changes check ✅ Passed The changes are primarily documentation-focused: tutorial section rewording, heading restructuring, content reorganization, and enabling prev/next navigation. A new role registration (oldheading_role) in docs/conf.py appears to support documentation features. All changes align with stated tutorial rework objectives and documentation maintenance.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
📝 Coding Plan
  • Generate coding plan for human review comments

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between d2aa226 and 8926f8a.

📒 Files selected for processing (6)
  • docs/conf.py
  • docs/tutorial/additional_features.rst
  • docs/tutorial/advanced.rst
  • docs/tutorial/basics.rst
  • docs/tutorial/interaction_visualization_reporting/tutorial.rst
  • docs/tutorial/tutorial.rst

@cademirch cademirch changed the title Docs: Rework tutorial docs: Rework tutorial Mar 13, 2026
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 | 🔴 Critical

Restore missing hyperlink targets to fix Sphinx build failure.

At Line 9 onward, references like Snakemake_, GNU Make_, Python_, Conda_, and Singularity_ 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

📥 Commits

Reviewing files that changed from the base of the PR and between fc54f78 and 0ec4f79.

⛔ Files ignored due to path filters (1)
  • docs/gurobi.log is excluded by !**/*.log
📒 Files selected for processing (6)
  • docs/conf.py
  • docs/tutorial/additional_features.rst
  • docs/tutorial/advanced.rst
  • docs/tutorial/basics.rst
  • docs/tutorial/interaction_visualization_reporting/tutorial.rst
  • docs/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

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
docs/tutorial/basics.rst (1)

481-482: Optional: Remove comma for smoother sentence flow.

The comma after plots/quals.svg slightly 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

📥 Commits

Reviewing files that changed from the base of the PR and between 4a97caf and 16121b3.

📒 Files selected for processing (2)
  • docs/tutorial/basics.rst
  • docs/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

@johanneskoester johanneskoester merged commit 4bba4a9 into snakemake:main Mar 17, 2026
58 of 59 checks passed
@johanneskoester
Copy link
Copy Markdown
Contributor

The remaining failure was unrelated and due to http issues.

@johanneskoester
Copy link
Copy Markdown
Contributor

Thanks a lot, great work!

johanneskoester pushed a commit that referenced this pull request Mar 24, 2026
🤖 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 -->
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.

Tutorial wrapper example out of date

2 participants