docs: Add documentation with example usage#27
Open
LKress wants to merge 1 commit intosnakemake:mainfrom
Open
Conversation
LKress
changed the title
📝 WalkthroughWalkthroughAdds documentation for the cluster-generic plugin: a short mention in Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ 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 Tip CodeRabbit can generate a title for your PR based on the changes.Add |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/further.md (1)
1-10: Consider adding a note about command-line usage.The example shows a profile-based configuration, which addresses the Issue
#14question about config files. Consider adding a brief note mentioning that these settings can also be provided as command-line arguments (e.g.,--executor cluster-generic --cluster-generic-submit-cmd "..."), which would provide users with both configuration approaches.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/further.md` around lines 1 - 10, Add a brief note under the Example setup that, besides profile files, the same options can be supplied on the command line; mention the relevant symbols such as executor, cluster-generic-submit-cmd and cluster-generic-cancel-cmd and show that users can pass them via flags (for example using --executor and --cluster-generic-submit-cmd) so readers know both the profile and CLI approaches are supported.
🤖 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/further.md`:
- Line 4: Replace the misspelled word "followig" with "following" in the
sentence that introduces the Snakemake profile example (the sentence containing
"The followig example Snakemake profile..."), ensuring the rest of the sentence
remains unchanged so it reads "The following example Snakemake profile...".
- Around line 6-10: Update the fenced code block containing the executor and
cluster-generic settings so it includes a language identifier for syntax
highlighting (use "yaml"); locate the block that starts with the three backticks
followed by lines like "executor: cluster-generic", "cluster-generic-submit-cmd:
sbatch --cpus-per-task {threads} --mem={resources.mem_mb} --job-name=smk-{rule}
--parsable", and "cluster-generic-cancel-cmd: scancel", and change the opening
fence from ``` to ```yaml to enable proper rendering.
---
Nitpick comments:
In `@docs/further.md`:
- Around line 1-10: Add a brief note under the Example setup that, besides
profile files, the same options can be supplied on the command line; mention the
relevant symbols such as executor, cluster-generic-submit-cmd and
cluster-generic-cancel-cmd and show that users can pass them via flags (for
example using --executor and --cluster-generic-submit-cmd) so readers know both
the profile and CLI approaches are supported.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 3fef6052-8e97-487f-97cf-0aabd772828f
📒 Files selected for processing (2)
docs/further.mddocs/intro.md
docs/further.md
Outdated
| ### Example setup | ||
|
|
||
| The cluster generic plugin enables access to workflow variables (such as `rule`, `resources`, or `threads`) within the strings used to define cluster generic plugin arguments. | ||
| This makes it possible to create custom configurations for running workflows on various cluster systems that support a submission command accepting the path to a job script. The followig example Snakemake profile (see [Profiles](https://snakemake.readthedocs.io/en/stable/executing/cli.html#profiles)) shows this for a custom SLURM execution configuration setup. Submitting jobs with this setup would result in having the rule name of the current job contained in the SLURM job name. |
There was a problem hiding this comment.
Fix typo: "followig" → "following".
There's a spelling error in the word "following".
📝 Proposed fix
-This makes it possible to create custom configurations for running workflows on various cluster systems that support a submission command accepting the path to a job script. The followig example Snakemake profile (see [Profiles](https://snakemake.readthedocs.io/en/stable/executing/cli.html#profiles)) shows this for a custom SLURM execution configuration setup. Submitting jobs with this setup would result in having the rule name of the current job contained in the SLURM job name.
+This makes it possible to create custom configurations for running workflows on various cluster systems that support a submission command accepting the path to a job script. The following example Snakemake profile (see [Profiles](https://snakemake.readthedocs.io/en/stable/executing/cli.html#profiles)) shows this for a custom SLURM execution configuration setup. Submitting jobs with this setup would result in having the rule name of the current job contained in the SLURM job name.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| This makes it possible to create custom configurations for running workflows on various cluster systems that support a submission command accepting the path to a job script. The followig example Snakemake profile (see [Profiles](https://snakemake.readthedocs.io/en/stable/executing/cli.html#profiles)) shows this for a custom SLURM execution configuration setup. Submitting jobs with this setup would result in having the rule name of the current job contained in the SLURM job name. | |
| This makes it possible to create custom configurations for running workflows on various cluster systems that support a submission command accepting the path to a job script. The following example Snakemake profile (see [Profiles](https://snakemake.readthedocs.io/en/stable/executing/cli.html#profiles)) shows this for a custom SLURM execution configuration setup. Submitting jobs with this setup would result in having the rule name of the current job contained in the SLURM job name. |
🧰 Tools
🪛 LanguageTool
[grammar] ~4-~4: Ensure spelling is correct
Context: ...accepting the path to a job script. The followig example Snakemake profile (see [Profile...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/further.md` at line 4, Replace the misspelled word "followig" with
"following" in the sentence that introduces the Snakemake profile example (the
sentence containing "The followig example Snakemake profile..."), ensuring the
rest of the sentence remains unchanged so it reads "The following example
Snakemake profile...".
LKress
force-pushed
the
14-missing-documentation-how-to-use
branch
from
f247867 to
74e704f
Compare
There was a problem hiding this comment.
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/further.md`:
- Around line 3-10: Add a new short subsection under the cluster generic plugin
docs that explicitly answers the three acceptance points: explain that the
cluster-generic executor is adapter-agnostic and show how to replace the example
"sbatch" command with other schedulers (mention LSF's "bsub" as an example)
while keeping the {threads}/{resources.mem_mb}/{rule} placeholders; state that
required resources should be declared in the Snakemake rule blocks (resources:
mem_mb: ..., threads: ...) and referenced from the profile via
cluster-generic-submit-cmd placeholders; and clarify configuration precedence by
saying submit/status/cancel commands (cluster-generic-submit-cmd,
cluster-generic-cancel-cmd and any status command) are typically set in the
profile or config.yaml for reproducibility but can be overridden on the CLI,
referencing the executor: cluster-generic entry and the three cluster-generic-*
keys so readers know exactly where to change them.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 3ee4368b-c785-4626-9ebf-59ef230f0edd
📒 Files selected for processing (2)
docs/further.mddocs/intro.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/intro.md
Comment on lines
+3
to
+10
| The cluster generic plugin enables access to workflow variables (such as `rule`, `resources`, or `threads`) within the strings used to define cluster generic plugin arguments. | ||
| This makes it possible to create custom configurations for running workflows on various cluster systems that support a submission command accepting the path to a job script. The following example Snakemake profile (see [Profiles](https://snakemake.readthedocs.io/en/stable/executing/cli.html#profiles)) shows this for a custom SLURM execution configuration setup. Submitting jobs with this setup would result in having the rule name of the current job contained in the SLURM job name. | ||
|
|
||
| ```yaml | ||
| executor: cluster-generic | ||
| cluster-generic-submit-cmd: sbatch --cpus-per-task {threads} --mem={resources.mem_mb} --job-name=smk-{rule} --parsable | ||
| cluster-generic-cancel-cmd: scancel | ||
| ``` |
There was a problem hiding this comment.
Documentation is still incomplete vs Issue #14 acceptance criteria.
This section adds a good SLURM example, but it does not yet answer the key “how to use” questions from the linked issue: (1) how to adapt for non-Slurm clusters (e.g., LSF), (2) where required resources should be defined, and (3) whether submit/status/cancel commands are configured in profile/config vs CLI. Please add a short subsection that explicitly covers those points so closing #14 is fully justified.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/further.md` around lines 3 - 10, Add a new short subsection under the
cluster generic plugin docs that explicitly answers the three acceptance points:
explain that the cluster-generic executor is adapter-agnostic and show how to
replace the example "sbatch" command with other schedulers (mention LSF's "bsub"
as an example) while keeping the {threads}/{resources.mem_mb}/{rule}
placeholders; state that required resources should be declared in the Snakemake
rule blocks (resources: mem_mb: ..., threads: ...) and referenced from the
profile via cluster-generic-submit-cmd placeholders; and clarify configuration
precedence by saying submit/status/cancel commands (cluster-generic-submit-cmd,
cluster-generic-cancel-cmd and any status command) are typically set in the
profile or config.yaml for reproducibility but can be overridden on the CLI,
referencing the executor: cluster-generic entry and the three cluster-generic-*
keys so readers know exactly where to change them.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add initial documentation with an example on how to use the plugin.
Closes #14
Summary by CodeRabbit