docs: Minor docs improvements by mrmattuschka · Pull Request #4089 · snakemake/snakemake

mrmattuschka · 2026-03-13T13:15:14Z

Minor additions to documentation (#4011 ):

make it clearer in the logs, that log: "some/file.txt" does not contain anything unless you redirect some output there
General How-to for using an executor plugin under Executing Workflows

QC

[N/A] The PR contains a test case for the changes or the changes are already covered by an existing test case. Docs only
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

Added comprehensive guide for using executor plugins – Instructions for locating, installing, and running workflows with executor plugins from the Snakemake catalog, including fallback and storage notes and example commands.
Clarified log directive behavior – Explains that log does not auto-redirect stdout/stderr and must be configured manually.
Updated CLI guidance and navigation – CLI non-local execution docs now reference executor plugins; TOC updated to include the new section.

coderabbitai · 2026-03-13T13:15:28Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 67858c02-8b5d-4389-b03a-944c1da7de83

📥 Commits

Reviewing files that changed from the base of the PR and between f713b9a and e2a84a4.

📒 Files selected for processing (1)

docs/executing/executors.rst

🚧 Files skipped from review as they are similar to previous changes (1)

docs/executing/executors.rst

📝 Walkthrough

Walkthrough

Adds new documentation on executor plugins, updates a CLI reference to point to executor plugins, inserts the new page into the docs toctree, and clarifies log-file behavior in rules documentation.

Changes

Cohort / File(s)	Summary
Executor plugins docs `docs/executing/executors.rst`, `docs/executing/cli.rst`, `docs/index.rst`	Adds a new "Using executor plugins" documentation page, updates the CLI doc to reference executor plugins via Sphinx cross-reference, and adds the new page to the documentation index toctree.
Rules logging note `docs/snakefiles/rules.rst`	Adds a note under Log-Files clarifying that `log` does not automatically redirect stdout/stderr to the log file and shows manual redirection guidance.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'docs: Minor docs improvements' is vague and generic, using non-descriptive terms that don't convey meaningful information about the specific documentation changes made.	Consider a more specific title such as 'docs: Add executor plugin guide and clarify log directive behavior' to better summarize the key changes.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description adequately covers the main changes, explicitly references the issue (`#4011`), explains the two key documentation additions, and properly completes the QC checklist for documentation-only changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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.}

coderabbitai

Actionable comments posted: 2

🧹 Nitpick comments (1)

docs/snakefiles/rules.rst (1)

1269-1269: Consider rephrasing for clarity.

The phrase "this you will still need to facilitate yourself" is slightly awkward. Consider rephrasing to "you will still need to handle this manually" or "you will still need to do this yourself" for better readability.

✨ Suggested rephrase

-.. note:: Using the ``log`` directive will not automatically redirect the rule's output towards the log file - this you will still need to facilitate yourself! The ``log`` directive merely prevents Snakemake from deleting the log file upon rule failure.
+.. note:: Using the ``log`` directive will not automatically redirect the rule's output towards the log file - you will still need to handle this manually! The ``log`` directive merely prevents Snakemake from deleting the log file upon rule failure.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/snakefiles/rules.rst` at line 1269, Replace the awkward phrase in the
sentence "Using the ``log`` directive will not automatically redirect the rule's
output towards the log file - this you will still need to facilitate yourself!"
with a clearer rephrase such as "Using the ``log`` directive will not
automatically redirect the rule's output to the log file — you will still need
to handle this manually." Locate the exact sentence (search for the quoted
fragment) and update the wording while preserving the surrounding note
formatting and the explanatory meaning.

🤖 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/executing/executors.rst`:
- Line 17: In the sentence in docs/executing/executors.rst that currently reads
"Depending on your compute environment you may also need install a :ref:`storage
plugin <storage-support>`...", insert the missing infinitive "to" so it reads
"may also need to install"; update that exact phrase in the file to correct the
grammar.
- Line 9: Fix the grammatical error in the sentence containing "suitable your"
by inserting the missing preposition so it reads "suitable for your"; locate the
sentence "Locate an executor suitable your cluster/cloud environment..." in
docs/executing/executors.rst and update it to "Locate an executor suitable for
your cluster/cloud environment and follow its respective installation
instructions."

---

Nitpick comments:
In `@docs/snakefiles/rules.rst`:
- Line 1269: Replace the awkward phrase in the sentence "Using the ``log``
directive will not automatically redirect the rule's output towards the log file
- this you will still need to facilitate yourself!" with a clearer rephrase such
as "Using the ``log`` directive will not automatically redirect the rule's
output to the log file — you will still need to handle this manually." Locate
the exact sentence (search for the quoted fragment) and update the wording while
preserving the surrounding note formatting and the explanatory meaning.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c98ca1f5-b83f-4183-bf55-466d463a2efe

📥 Commits

Reviewing files that changed from the base of the PR and between 50e1ecd and f713b9a.

📒 Files selected for processing (4)

docs/executing/cli.rst
docs/executing/executors.rst
docs/index.rst
docs/snakefiles/rules.rst

docs/executing/executors.rst

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

johanneskoester

Fantastic!

🤖 I have created a release *beep* *boop* --- ## [9.17.0](v9.16.3...v9.17.0) (2026-03-13) ### Features * Allow storing snakemake metadata in files or databases ([#4012](#4012)) ([dd75f31](dd75f31)) * Allow to specify comparison command per-unit test ([#3956](#3956)) ([b88171c](b88171c)) * job table orderd topological when run is started ([#4018](#4018)) ([75cf506](75cf506)) * lambda functions for priority in rules ([#3253](#3253)) ([d2aa226](d2aa226)) * Make on... directive of modules accessible ([#4050](#4050)) ([e9f2e1c](e9f2e1c)) ### Bug Fixes * adjust conda tests to not fail on apple silicon; fix [#4040](#4040) ([#4049](#4049)) ([f5b0142](f5b0142)) * allow "--containerize apptainer" to output apptainer format instead of dockerfile ([#4030](#4030)) ([f5cac30](f5cac30)) * apptainer command not recognized when singularity is absent ([#4010](#4010)) ([b8162e2](b8162e2)) * capture stderr when tests fail ([#3995](#3995)) ([97d74ba](97d74ba)) * **docs:** make Data-dependent conditional execution a complete example ([#4043](#4043)) ([3a1d7f2](3a1d7f2)) * don't build the DAG when running unlock. Fixes [#4000](#4000) and [#198](#198) ([#4007](#4007)) ([acf79fd](acf79fd)) * Ensure pixi tasks may be run as advertised ([#4046](#4046)) ([88253c2](88253c2)) * fix checkpoint handling corner cases ([#3870](#3870) and [#3559](#3559)) ([#4015](#4015)) ([63f4257](63f4257)) * issue 3642 ([#4054](#4054)) ([76e6fc2](76e6fc2)) * issue 3815 ([#4026](#4026)) ([b0eec96](b0eec96)) * logging None in shellcmd context causes error ([#4064](#4064)) ([d0652cd](d0652cd)) * lookup function returns default value for empty DataFrame queries ([#4056](#4056)) ([f71de97](f71de97)) * make `cache: omit-software` a rule specific property ([#4085](#4085)) ([034a9e7](034a9e7)) * reduce number of tests leaving temporary files behind ([#4033](#4033)) ([a3a1c97](a3a1c97)) * regression in dynamic resource handling ([#4038](#4038)) ([f2c554a](f2c554a)) * somewhat shorter announce message ([#4080](#4080)) ([57efc71](57efc71)) ### Performance Improvements * switch reretry with tenacity; decouple container classes (with Python 3.7 compat for old scripts) from rest of the codebase (enabling moving to newer python versions) ([#4032](#4032)) ([ffb19e7](ffb19e7)) ### Documentation * Add AI-assisted contributions policy to contributing guidelines ([#4051](#4051)) ([dd70526](dd70526)) * **codebase:** Update & simplify plugin architecture section ([#4052](#4052)) ([176cf63](176cf63)) * Correct workflow.source_path() description in documentation ([#4036](#4036)) ([45883c5](45883c5)) * fixed wrong code example for collect() function ([#4037](#4037)) ([5c85ed8](5c85ed8)) * Minor docs improvements ([#4089](#4089)) ([29ea226](29ea226)) * switch to sphinx_design for tabs ([#3976](#3976)) ([9674614](9674614)) * typo in the migration table breaking a pip install command ([#4024](#4024)) ([66f9dda](66f9dda)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

mrmattuschka and others added 5 commits March 13, 2026 10:56

Added note on log directive not redirecting stdout

2eff27a

WIP: using executor plugins

1017479

Guide on using executor plugins

8419424

Link from cli to executors, link from executors to storage plugins

a0a45fa

Merge branch 'main' into minor-docs-improvements

f713b9a

mrmattuschka mentioned this pull request Mar 13, 2026

docs: tracking issue for documentation improvements at the Snakemake Hackathon 2026 #4011

Open

15 tasks

mrmattuschka marked this pull request as ready for review March 13, 2026 13:18

mrmattuschka requested a review from johanneskoester as a code owner March 13, 2026 13:18

coderabbitai bot reviewed Mar 13, 2026

View reviewed changes

docs/executing/executors.rst Outdated Show resolved Hide resolved

docs/executing/executors.rst Outdated Show resolved Hide resolved

johanneskoester and others added 2 commits March 13, 2026 14:24

Apply suggestion from @coderabbitai[bot]

23d9fd9

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Apply suggestion from @coderabbitai[bot]

e2a84a4

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

johanneskoester approved these changes Mar 13, 2026

View reviewed changes

johanneskoester enabled auto-merge (squash) March 13, 2026 13:26

johanneskoester merged commit 29ea226 into snakemake:main Mar 13, 2026
60 checks passed

snakemake-bot mentioned this pull request Mar 13, 2026

chore(main): release 9.17.0 #3977

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Minor docs improvements#4089

docs: Minor docs improvements#4089
johanneskoester merged 7 commits intosnakemake:mainfrom
mrmattuschka:minor-docs-improvements

mrmattuschka commented Mar 13, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Mar 13, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

❌ Failed checks (1 inconclusive)

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

johanneskoester left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mrmattuschka commented Mar 13, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

QC

Summary by CodeRabbit

Documentation

Uh oh!

coderabbitai bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

❌ Failed checks (1 inconclusive)

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

johanneskoester left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mrmattuschka commented Mar 13, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Mar 13, 2026 •

edited

Loading