From 672a5b6660f5cc3c758eef15b498a0900e07ab6c Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 18:25:54 +0100 Subject: [PATCH 01/13] docs(source): Add docstring to plugin collection --- source/collect_plugins.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/collect_plugins.py b/source/collect_plugins.py index eda915f..ba1a85d 100644 --- a/source/collect_plugins.py +++ b/source/collect_plugins.py @@ -154,6 +154,13 @@ def aux_info(self, metadata_collector) -> Dict[str, Any]: return {} def collect_plugins(self, plugins, packages, templates): + """ + Collect plugins of the type of the corresponding plugin type collector class. + Plugins are selected from the set of ALL pypi packages by matching names to the + expected prefix of 'snakemake-{plugin_type}-plugin-'. For each matching package + metadata is then extracted, the provided `templates` are rendered using this + information, and the plugin name is appended to `plugins`. + """ plugin_type = self.plugin_type() plugin_dir = Path("plugins") / plugin_type if plugin_dir.exists(): From 998170c37f2da2ad90c3248e379434315d3add87 Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 18:25:54 +0100 Subject: [PATCH 02/13] docs(source): Add docstring to metadata collector --- source/collect_plugins.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/collect_plugins.py b/source/collect_plugins.py index ba1a85d..746dac3 100644 --- a/source/collect_plugins.py +++ b/source/collect_plugins.py @@ -50,6 +50,11 @@ def log(self, package: str) -> None: class MetadataCollector: + """ + Collect metadata on a plugin `package` of a specific `plugin_type` by installing it + in a temporary working directory specific to each class instance. + """ + def __init__(self, package: str, plugin_type: str, version: str): self.envname = uuid.uuid4().hex self.package = package From 7bb76154f0bb502c8d6cb51a27426f5f3041d551 Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 18:25:54 +0100 Subject: [PATCH 03/13] docs(source): Add docstring to pixi_add The function name by itself is a bit ambiguous. --- source/collect_plugins.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/collect_plugins.py b/source/collect_plugins.py index 746dac3..77dbc3e 100644 --- a/source/collect_plugins.py +++ b/source/collect_plugins.py @@ -98,6 +98,10 @@ def __enter__(self): ) def pixi_add(args=None): + """ + Add the package for which metadata is to be parsed to the temporary + workspace. + """ args = args or [] self._run(["pixi", "add", f"{self.package}=={self.version}"] + args) From 5331cbac683155bc3201eafd6963b0a4453bb8b8 Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 18:25:54 +0100 Subject: [PATCH 04/13] docs(README): Link to Snakemake plugin doc --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d3713dd..15ccd50 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ # snakemake-plugin-catalog -An automatically updated catalog of Snakemake plugins and their documentation +An automatically updated catalog of +[Snakemake plugins](https://snakemake.readthedocs.io/en/stable/project_info/codebase.html#plugins) +and their documentation. From c05aac5be90c78125b9858f74bef342e32becbff Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 18:25:54 +0100 Subject: [PATCH 05/13] docs(README): Link to catalog website --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 15ccd50..b862e72 100644 --- a/README.md +++ b/README.md @@ -2,4 +2,7 @@ An automatically updated catalog of [Snakemake plugins](https://snakemake.readthedocs.io/en/stable/project_info/codebase.html#plugins) -and their documentation. +and their documentation. See + (generated from +[this template](/source/_templates/index.rst.j2)) for a general overview of the +catalog. From e0444c62be43ad37233073f90fef62173dc2effc Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 18:25:54 +0100 Subject: [PATCH 06/13] docs(templates): Link to Snakemake codebase docs To make the plugin section there more prominent. --- source/_templates/index.rst.j2 | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/_templates/index.rst.j2 b/source/_templates/index.rst.j2 index 989b021..37783ea 100644 --- a/source/_templates/index.rst.j2 +++ b/source/_templates/index.rst.j2 @@ -11,6 +11,8 @@ The following illustration depicts the general architecture of Snakemake and its .. image:: _static/snakemake-architecture.svg :alt: Snakemake plugin architecture +See the corresponding `section `__ in the Snakemake architecture docs for more details. + Contributing ------------ From cfb7860b486e0a17c8a50a6fbf99e2b0adce7f06 Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 18:44:20 +0100 Subject: [PATCH 07/13] chore(pixi): Fix build-single task Previously it was not possible to specify different packages due to changes in how Pixi handles env variable precedence. --- pixi.toml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/pixi.toml b/pixi.toml index 18fc3a6..59fda25 100644 --- a/pixi.toml +++ b/pixi.toml @@ -7,7 +7,12 @@ version = "0.1.0" [tasks] build = "sphinx-build source build" -build-single = { cmd = "sphinx-build source build", env = { TEST_PACKAGES = "snakemake-executor-plugin-cluster-generic" } } +build-single = { cmd = """ + export TEST_PACKAGES={{ packages }} && \ + sphinx-build source build + """, args = [ + { "arg" = "packages", "default" = "snakemake-executor-plugin-cluster-generic" } +] } apply-qc = [{ task = "style", environment = "style" }] qc = [{ task = "lint", environment = "style" }] From 420386df959fec9b72063d5fac18a8d47a17c29d Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 18:53:32 +0100 Subject: [PATCH 08/13] chore(pixi): Give build-single own table Task is too complex to be left inline. --- pixi.toml | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/pixi.toml b/pixi.toml index 59fda25..b8b769a 100644 --- a/pixi.toml +++ b/pixi.toml @@ -7,15 +7,18 @@ version = "0.1.0" [tasks] build = "sphinx-build source build" -build-single = { cmd = """ - export TEST_PACKAGES={{ packages }} && \ - sphinx-build source build - """, args = [ - { "arg" = "packages", "default" = "snakemake-executor-plugin-cluster-generic" } -] } apply-qc = [{ task = "style", environment = "style" }] qc = [{ task = "lint", environment = "style" }] +[tasks.build-single] +cmd = """ +export TEST_PACKAGES="{{ packages }}" && \ +sphinx-build source build +""" +args = [ + { "arg" = "packages", "default" = "snakemake-executor-plugin-cluster-generic" } +] + [dependencies] sphinx = ">=8.2.3,<9" python = ">=3.11.0,<4" From 80cecb1985700015c55002f56e05f6eb8cc4f6d5 Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 18:59:10 +0100 Subject: [PATCH 09/13] chore(pixi): Add description to build-single --- pixi.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pixi.toml b/pixi.toml index b8b769a..4c01988 100644 --- a/pixi.toml +++ b/pixi.toml @@ -11,6 +11,7 @@ apply-qc = [{ task = "style", environment = "style" }] qc = [{ task = "lint", environment = "style" }] [tasks.build-single] +description = "Build docs for individual plugins. Separate `package`s with ',' to specify multiple plugins." cmd = """ export TEST_PACKAGES="{{ packages }}" && \ sphinx-build source build From 151e7292e866a11d045690625bb8b21dcb49b935 Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 19:03:55 +0100 Subject: [PATCH 10/13] refactor(pixi): Rename build-specific task More descriptive, it's possible to build multiple plugin docs with this task. --- .github/workflows/ci.yml | 2 +- pixi.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9136e6a..27b98a5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,7 +31,7 @@ jobs: cache: true - name: Building - run: pixi run build-single + run: pixi run build-specific test: runs-on: ubuntu-latest diff --git a/pixi.toml b/pixi.toml index 4c01988..8ef9c9d 100644 --- a/pixi.toml +++ b/pixi.toml @@ -10,7 +10,7 @@ build = "sphinx-build source build" apply-qc = [{ task = "style", environment = "style" }] qc = [{ task = "lint", environment = "style" }] -[tasks.build-single] +[tasks.build-specific] description = "Build docs for individual plugins. Separate `package`s with ',' to specify multiple plugins." cmd = """ export TEST_PACKAGES="{{ packages }}" && \ From 60af0d4579c125244b1410244475a551361e75db Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 18:25:54 +0100 Subject: [PATCH 11/13] docs(README): Add short contributing section --- README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/README.md b/README.md index b862e72..30bd679 100644 --- a/README.md +++ b/README.md @@ -6,3 +6,29 @@ and their documentation. See (generated from [this template](/source/_templates/index.rst.j2)) for a general overview of the catalog. + +## Contributing + +> WARNING: The `build` task is designed to run on a GitHub runner and will +> install essentially arbitrary code on the machine it is run on. Don't run it +> unless you understand the risk involved! The same goes for `build-specific` if +> you don't understand the plugin you run it on. + +### Software environment + +Like the rest of the Snakemake ecosystem, the plugin catalog uses +[Pixi](https://pixi.prefix.dev/latest/) to manage software environments and +common development and deployment tasks. See their docs for detailed information +on setup and task running. + +### Development + +After making changes to the code, ensure the code is consistently formatted by +doing `pixi run style`. If you make changes to the Jinja templates used to build +the catalog, ensure the underlying rst files follow the general Snakemake +[documentation guidelines](https://snakemake.readthedocs.io/en/stable/project_info/contributing.html#documentation-guidelines). + +### Testing + +Currently there are no unit-tests. Checking whether the code works as expected +is done by building individual plugin docs via the `build-specific` Pixi task. From a321a6c34dedfc243c61f7a37de3d5884ed7d5a3 Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Wed, 11 Mar 2026 19:12:59 +0100 Subject: [PATCH 12/13] chore(pixi): Add slurm plugin to build-specific The single cluster-generic plugin does not contain additional docs, which the slurm plugin does. Adding the latter effectively increases test coverage. --- pixi.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pixi.toml b/pixi.toml index 8ef9c9d..5a36ef9 100644 --- a/pixi.toml +++ b/pixi.toml @@ -17,7 +17,7 @@ export TEST_PACKAGES="{{ packages }}" && \ sphinx-build source build """ args = [ - { "arg" = "packages", "default" = "snakemake-executor-plugin-cluster-generic" } + { "arg" = "packages", "default" = "snakemake-executor-plugin-cluster-generic,snakemake-executor-plugin-slurm" } ] [dependencies] From 43b5ada094e80db3aaf505e4aa8eda351e710cea Mon Sep 17 00:00:00 2001 From: Jonas Freimuth Date: Thu, 12 Mar 2026 09:31:31 +0100 Subject: [PATCH 13/13] feat(catalog): Strip test package whitespace As suggested by CodeRabbit (). --- source/collect_plugins.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/collect_plugins.py b/source/collect_plugins.py index 77dbc3e..5be302d 100644 --- a/source/collect_plugins.py +++ b/source/collect_plugins.py @@ -20,7 +20,11 @@ TEST_PACKAGES = ( - os.environ.get("TEST_PACKAGES").split(",") + [ + package.strip() + for package in os.environ.get("TEST_PACKAGES").split(",") + if package.strip() + ] if "TEST_PACKAGES" in os.environ else None )