docs(codebase): Update & simplify plugin architecture section by jonasfreimuth · Pull Request #4052 · snakemake/snakemake

jonasfreimuth · 2026-03-11T11:33:25Z

Remove details on how to contribute plugins as this should not be covered in the codebase part of the architecture section. If we have such docs in unexpected places, it is rather likely to go out of date. This has happened here already with the docs still mentioning poetry prior to this PR.

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).

This PR is purely a docs change.

Summary by CodeRabbit

Documentation
- Added a Slurm executor plugin reference in the plugin catalog with a link and example output rendering.
- Streamlined scaffolding guidance: replaced Poetry-centric instructions with Snakedeploy and Pixi references.
- Replaced lengthy scaffold and storage examples with concise pointers to scaffold examples and added a note on continuous testing via GitHub Actions and guidance for deploying additional services.

coderabbitai · 2026-03-11T11:33:36Z

📝 Walkthrough

Walkthrough

Replaced Poetry-based scaffolding instructions with references to Snakedeploy/Pixi scaffolding, added links to the Slurm executor plugin and its catalog-rendered output, removed long StorageProvider/scaffolding examples, and added a note about CI testing via .github/workflows/ci.yml.

Changes

Cohort / File(s)	Summary
Documentation Updates `docs/project_info/codebase.rst`	Removed detailed Poetry scaffolding and StorageProvider example; added references to Snakedeploy and Pixi scaffolding examples, added links to the Slurm executor plugin and its catalog output, and noted CI/testing via `.github/workflows/ci.yml`.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: updating and simplifying the plugin architecture section in documentation.
Description check	✅ Passed	The description follows the template structure with a clear explanation of changes and completed QC checklist items.
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

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.}

jonasfreimuth · 2026-03-11T15:24:39Z

I have changed this to remove less. It should now be ready to be merged without requiring any changes to the plugin catalog.

coderabbitai

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/project_info/codebase.rst`:
- Around line 147-148: Correct the two typographical issues in the quoted
sentences: change "for a example" to "for an example" in the phrase starting
with "See the `Slurm executor plugin <...docs>`__" and remove the extra space
before the period in the sentence that starts "You can see how its output is
rendered in the catalog `here <...slurm.html>`__ ."; update those strings
accordingly so they read "for an example" and end with a single period
immediately after the closing backticks.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 220581c2-1a29-449a-b96e-7435b249675c

📥 Commits

Reviewing files that changed from the base of the PR and between f5b0142 and e4cc45c.

📒 Files selected for processing (1)

docs/project_info/codebase.rst

docs/project_info/codebase.rst

jonasfreimuth · 2026-03-11T15:37:39Z

Closes #4041

coderabbitai

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/project_info/codebase.rst (1)

160-160: ⚠️ Potential issue | 🟡 Minor

Correct the capitalization of "GitHub".

"Github" should be "GitHub" with a capital H, as it is a proper noun referring to the brand name.

📝 Proposed fix

-Continuous testing is conducted via Github Actions, defined in the file ``.github/workflows/ci.yml``.
+Continuous testing is conducted via GitHub Actions, defined in the file ``.github/workflows/ci.yml``.

🤖 Prompt for AI Agents

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

In `@docs/project_info/codebase.rst` at line 160, Update the occurrence of the
brand name "Github" to the correct capitalization "GitHub" in the sentence that
references the workflow file (the string ".github/workflows/ci.yml"), preserving
the surrounding inline code/backticks formatting; also search the document for
any other instances of "Github" and correct them to "GitHub" to ensure
consistent, brand-accurate usage.

♻️ Duplicate comments (1)

docs/project_info/codebase.rst (1)

148-148: ⚠️ Potential issue | 🟡 Minor

Remove extra space before the period.

There is an extra space before the period at the end of the line. The link should be followed immediately by a period without a space.

📝 Proposed fix

-You can see how its output is rendered in the catalog `here <https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html>`__ .
+You can see how its output is rendered in the catalog `here <https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html>`__.

🤖 Prompt for AI Agents

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

In `@docs/project_info/codebase.rst` at line 148, In the sentence containing the
catalog link "here
<https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html>`__
.", remove the stray space before the period so the link is immediately followed
by the period (i.e. change "`__ .” to "`__.”) to correct the punctuation.

🤖 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/project_info/codebase.rst`:
- Line 156: In the sentence containing the Snakedeploy scaffold link (the inline
reStructuredText reference to
https://github.com/snakemake/snakedeploy/blob/main/snakedeploy/templates/plugins/storage-plugins/init.py),
remove the stray space before the closing parenthesis so the link is immediately
followed by ")" (i.e., change "init.py>`__ )" to "init.py>`__)"). Ensure no
other spacing around that closing parenthesis is altered.

---

Outside diff comments:
In `@docs/project_info/codebase.rst`:
- Line 160: Update the occurrence of the brand name "Github" to the correct
capitalization "GitHub" in the sentence that references the workflow file (the
string ".github/workflows/ci.yml"), preserving the surrounding inline
code/backticks formatting; also search the document for any other instances of
"Github" and correct them to "GitHub" to ensure consistent, brand-accurate
usage.

---

Duplicate comments:
In `@docs/project_info/codebase.rst`:
- Line 148: In the sentence containing the catalog link "here
<https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html>`__
.", remove the stray space before the period so the link is immediately followed
by the period (i.e. change "`__ .” to "`__.”) to correct the punctuation.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 894cb05a-c0a7-46df-aff8-3f0aec4baf87

📥 Commits

Reviewing files that changed from the base of the PR and between e4cc45c and 8c959cb.

📒 Files selected for processing (1)

docs/project_info/codebase.rst

docs/project_info/codebase.rst

jonasfreimuth · 2026-03-11T17:31:17Z

I will also rebase this onto our current main.

Switch it to Pixi & Snakedeploy to be in line with the generally accepted method outlined in the plugin catalog.

This is too practical for the architecture section and too prone to going out of date, as has happened with the move to Pixi.

Having an illustrative example is good, but I fear this may go out date as well. So I'd rather point to the actual scaffold in Snakedeploy.

coderabbitai

♻️ Duplicate comments (2)

docs/project_info/codebase.rst (2)

156-156: ⚠️ Potential issue | 🟡 Minor

Remove extra space before the closing parenthesis.

There is an extra space before the closing parenthesis at the end of line 156.

📝 Proposed fix

-Have a look at the scaffold files in Snakedeploy (e.g. the init file for `storage plugins <https://github.com/snakemake/snakedeploy/blob/main/snakedeploy/templates/plugins/storage-plugins/init.py>`__ ) on how that may look.
+Have a look at the scaffold files in Snakedeploy (e.g. the init file for `storage plugins <https://github.com/snakemake/snakedeploy/blob/main/snakedeploy/templates/plugins/storage-plugins/init.py>`__) on how that may look.

🤖 Prompt for AI Agents

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

In `@docs/project_info/codebase.rst` at line 156, The sentence referencing the
scaffold files contains an extra space before the closing parenthesis in the
snippet "storage plugins
<https://github.com/snakemake/snakedeploy/blob/main/snakedeploy/templates/plugins/storage-plugins/init.py>`__
)"; edit that line in docs/project_info/codebase.rst to remove the stray space
so the closing sequence is ")": "...init.py>`__)".

147-148: ⚠️ Potential issue | 🟡 Minor

Fix grammatical and spacing errors.

Line 147 has a grammatical error ("for a example" should be "for an example"), and Line 148 has an extra space before the period.

📝 Proposed fix

-See the `Slurm executor plugin <https://github.com/snakemake/snakemake-executor-plugin-slurm/tree/main/docs>`__ for a example on how that may be specified.
-You can see how its output is rendered in the catalog `here <https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html>`__ .
+See the `Slurm executor plugin <https://github.com/snakemake/snakemake-executor-plugin-slurm/tree/main/docs>`__ for an example on how that may be specified.
+You can see how its output is rendered in the catalog `here <https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html>`__.

🤖 Prompt for AI Agents

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

In `@docs/project_info/codebase.rst` around lines 147 - 148, Fix the grammatical
and spacing mistakes in the two sentences: change "for a example" to "for an
example" in the Slurm executor plugin reference sentence (the sentence
containing "Slurm executor plugin
<https://github.com/snakemake/snakemake-executor-plugin-slurm/tree/main/docs>")
and remove the extra space before the period in the catalog link sentence (the
sentence containing "catalog `here
<https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html>`__
.").

🤖 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/project_info/codebase.rst`:
- Line 156: The sentence referencing the scaffold files contains an extra space
before the closing parenthesis in the snippet "storage plugins
<https://github.com/snakemake/snakedeploy/blob/main/snakedeploy/templates/plugins/storage-plugins/init.py>`__
)"; edit that line in docs/project_info/codebase.rst to remove the stray space
so the closing sequence is ")": "...init.py>`__)".
- Around line 147-148: Fix the grammatical and spacing mistakes in the two
sentences: change "for a example" to "for an example" in the Slurm executor
plugin reference sentence (the sentence containing "Slurm executor plugin
<https://github.com/snakemake/snakemake-executor-plugin-slurm/tree/main/docs>")
and remove the extra space before the period in the catalog link sentence (the
sentence containing "catalog `here
<https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html>`__
.").

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 888e79f7-39bb-4053-bd5f-449215a02bc3

📥 Commits

Reviewing files that changed from the base of the PR and between 8c959cb and f4bb5f7.

📒 Files selected for processing (1)

docs/project_info/codebase.rst

coderabbitai

♻️ Duplicate comments (1)

docs/project_info/codebase.rst (1)

147-148: ⚠️ Potential issue | 🟡 Minor

Fix grammatical and spacing errors.

Line 147 has a grammatical error ("for a example" should be "for an example"), and Line 148 has an extra space before the period.

📝 Proposed fix

-See the `Slurm executor plugin <https://github.com/snakemake/snakemake-executor-plugin-slurm/tree/main/docs>`__ for a example on how that may be specified.
-You can see how its output is rendered in the catalog `here <https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html>`__ .
+See the `Slurm executor plugin <https://github.com/snakemake/snakemake-executor-plugin-slurm/tree/main/docs>`__ for an example on how that may be specified.
+You can see how its output is rendered in the catalog `here <https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/slurm.html>`__.

🤖 Prompt for AI Agents

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

In `@docs/project_info/codebase.rst` around lines 147 - 148, Fix the grammar and
spacing in the two sentences: change "for a example" to "for an example" in the
sentence that references the Slurm executor plugin (the line containing "Slurm
executor plugin <https://github.com/.../docs>`__") and remove the stray space
before the period in the sentence that references the catalog "here
<https://snakemake.github.io/.../slurm.html>`__ .", so the period immediately
follows the closing emphasis markup.

🤖 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/project_info/codebase.rst`:
- Around line 147-148: Fix the grammar and spacing in the two sentences: change
"for a example" to "for an example" in the sentence that references the Slurm
executor plugin (the line containing "Slurm executor plugin
<https://github.com/.../docs>`__") and remove the stray space before the period
in the sentence that references the catalog "here
<https://snakemake.github.io/.../slurm.html>`__ .", so the period immediately
follows the closing emphasis markup.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 70b50716-7e9f-4759-942f-03159c7cb316

📥 Commits

Reviewing files that changed from the base of the PR and between f4bb5f7 and 8335a05.

📒 Files selected for processing (1)

docs/project_info/codebase.rst

- Add simple docstrings to potentially confusing functions for plugin collection & metadata extraction. - Restore functionality to the build task for individual plugins, rename it for clarity, and also include the slurm executor for increased test coverage. - Expand README with links to the Snakemake plugin doc & a short contributing section. I have realized as part of snakemake/snakemake#4052 that there is sufficient docs on documenting plugins, it was just not easy to discover. That PR, along with this, should close #27.  ## Summary by CodeRabbit * **Documentation** * Expanded README with contributing, environment, development, testing guidance and a build warning * Added cross-reference to plugin architecture docs * Clarified plugin collection and temporary workspace behavior in documentation * **Chores** * Updated CI test job command * Added a per-plugin documentation build task and expanded build/tooling configuration

🤖 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).

jonasfreimuth force-pushed the 4041-inconsistent-plugin-contribution-docs-between-catalog-and-snakemake branch 4 times, most recently from 32d77ef to 764ba4a Compare March 11, 2026 15:21

jonasfreimuth changed the title ~~docs(codebase): Replace plugin contribution details~~ docs(codebase): Update & simplify plugin architecture section Mar 11, 2026

jonasfreimuth force-pushed the 4041-inconsistent-plugin-contribution-docs-between-catalog-and-snakemake branch from 764ba4a to e4cc45c Compare March 11, 2026 15:26

jonasfreimuth marked this pull request as ready for review March 11, 2026 15:26

jonasfreimuth requested a review from johanneskoester as a code owner March 11, 2026 15:26

coderabbitai bot reviewed Mar 11, 2026

View reviewed changes

docs/project_info/codebase.rst Outdated Show resolved Hide resolved

jonasfreimuth force-pushed the 4041-inconsistent-plugin-contribution-docs-between-catalog-and-snakemake branch from e4cc45c to 8c959cb Compare March 11, 2026 15:35

jonasfreimuth linked an issue Mar 11, 2026 that may be closed by this pull request

Inconsistent plugin contribution docs between catalog and Snakemake #4041

Closed

coderabbitai bot reviewed Mar 11, 2026

View reviewed changes

docs/project_info/codebase.rst Outdated Show resolved Hide resolved

jonasfreimuth added this to Snakemake Hackathon 2026 Mar 11, 2026

jonasfreimuth moved this to In review in Snakemake Hackathon 2026 Mar 11, 2026

jonasfreimuth self-assigned this Mar 11, 2026

johanneskoester reviewed Mar 11, 2026

View reviewed changes

docs/project_info/codebase.rst Outdated Show resolved Hide resolved

jonasfreimuth force-pushed the 4041-inconsistent-plugin-contribution-docs-between-catalog-and-snakemake branch from 8c959cb to f4bb5f7 Compare March 11, 2026 17:29

jonasfreimuth added 4 commits March 11, 2026 18:31

docs(codebase): Remove poetry from plugin docs

7f87712

Switch it to Pixi & Snakedeploy to be in line with the generally accepted method outlined in the plugin catalog.

docs(codebase): Remove section on plugin repo init

a224f8d

This is too practical for the architecture section and too prone to going out of date, as has happened with the move to Pixi.

docs(codebase): Replace plugin scaffold example

aefe152

Having an illustrative example is good, but I fear this may go out date as well. So I'd rather point to the actual scaffold in Snakedeploy.

docs(codebase): Mention plugin example for catalog

8335a05

jonasfreimuth force-pushed the 4041-inconsistent-plugin-contribution-docs-between-catalog-and-snakemake branch from f4bb5f7 to 8335a05 Compare March 11, 2026 17:31

coderabbitai bot reviewed Mar 11, 2026

View reviewed changes

jonasfreimuth requested a review from johanneskoester March 11, 2026 17:43

jonasfreimuth mentioned this pull request Mar 11, 2026

docs: Expand documentation snakemake/snakemake-plugin-catalog#29

Merged

johanneskoester approved these changes Mar 12, 2026 •

edited

Loading

View reviewed changes

johanneskoester merged commit 176cf63 into snakemake:main Mar 12, 2026
60 checks passed

github-project-automation bot moved this from In review to Done in Snakemake Hackathon 2026 Mar 12, 2026

snakemake-bot mentioned this pull request Mar 12, 2026

chore(main): release 9.17.0 #3977

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(codebase): Update & simplify plugin architecture section#4052

docs(codebase): Update & simplify plugin architecture section#4052
johanneskoester merged 4 commits intosnakemake:mainfrom
TRON-Bioinformatics:4041-inconsistent-plugin-contribution-docs-between-catalog-and-snakemake

jonasfreimuth commented Mar 11, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Mar 11, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Uh oh!

jonasfreimuth commented Mar 11, 2026

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

jonasfreimuth commented Mar 11, 2026

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

jonasfreimuth commented Mar 11, 2026

Uh oh!

coderabbitai bot left a comment

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

QC

Summary by CodeRabbit

Uh oh!

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

Uh oh!

Walkthrough

Changes

Estimated code review effort

Uh oh!

jonasfreimuth commented Mar 11, 2026

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jonasfreimuth commented Mar 11, 2026

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jonasfreimuth commented Mar 11, 2026

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jonasfreimuth commented Mar 11, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Mar 11, 2026 •

edited

Loading