docs: clearly explain report rendering to ZIP archive#3357
Merged
dlaehnemann merged 7 commits intomainfrom Mar 10, 2025
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughThis pull request updates the Snakemake documentation and CLI help text for report generation. The documentation now includes additional sections detailing how to include results in reports, produce self-contained HTML and ZIP archive reports, create partial reports, and apply custom layouts. It also clarifies that generated reports contain runtime statistics, provenance information, and workflow topology by default. In the CLI, the help text for the Changes
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms (40)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/snakefiles/reporting.rst(5 hunks)snakemake/cli.py(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`**/*.py`: Do not try to improve formatting. Do not suggest ...
**/*.py: Do not try to improve formatting.
Do not suggest type annotations for functions that are defined inside of functions or methods.
Do not suggest type annotation of theselfargument of methods.
Do not suggest type annotation of theclsargument of classmethods.
Do not suggest return type annotation if a function or method does not contain areturnstatement.
snakemake/cli.py
🪛 GitHub Check: Check for spelling errors
docs/snakefiles/reporting.rst
[failure] 10-10:
complext ==> complexity, complex
🪛 GitHub Actions: Codespell
docs/snakefiles/reporting.rst
[error] 10-10: codespell: 'complext' should be corrected to 'complexity, complex'.
⏰ Context from checks skipped due to timeout of 90000ms (40)
- GitHub Check: testing (10, 3.12, dash)
- GitHub Check: testing (10, 3.12, bash)
- GitHub Check: testing (10, 3.11, bash)
- GitHub Check: testing (9, 3.12, dash)
- GitHub Check: testing (9, 3.12, bash)
- GitHub Check: testing (9, 3.11, bash)
- GitHub Check: testing (8, 3.12, dash)
- GitHub Check: testing (8, 3.12, bash)
- GitHub Check: testing (8, 3.11, bash)
- GitHub Check: testing (7, 3.12, dash)
- GitHub Check: testing (7, 3.12, bash)
- GitHub Check: testing (7, 3.11, bash)
- GitHub Check: testing (6, 3.12, dash)
- GitHub Check: testing (6, 3.12, bash)
- GitHub Check: testing (6, 3.11, bash)
- GitHub Check: testing (5, 3.12, dash)
- GitHub Check: testing (5, 3.12, bash)
- GitHub Check: testing (5, 3.11, bash)
- GitHub Check: testing (4, 3.12, dash)
- GitHub Check: testing (4, 3.12, bash)
- GitHub Check: testing (4, 3.11, bash)
- GitHub Check: testing (3, 3.12, dash)
- GitHub Check: testing (3, 3.12, bash)
- GitHub Check: testing-windows (10)
- GitHub Check: testing (3, 3.11, bash)
- GitHub Check: testing-windows (9)
- GitHub Check: testing (2, 3.12, dash)
- GitHub Check: testing-windows (8)
- GitHub Check: testing (2, 3.12, bash)
- GitHub Check: testing-windows (7)
- GitHub Check: testing (2, 3.11, bash)
- GitHub Check: testing-windows (6)
- GitHub Check: testing (1, 3.12, dash)
- GitHub Check: testing-windows (5)
- GitHub Check: testing (1, 3.12, bash)
- GitHub Check: testing-windows (4)
- GitHub Check: testing (1, 3.11, bash)
- GitHub Check: testing-windows (3)
- GitHub Check: testing-windows (2)
- GitHub Check: testing-windows (1)
🔇 Additional comments (7)
snakemake/cli.py (1)
957-965: Great improvement to the report documentation!The updated help text for the
--reportargument is much clearer. It now properly explains:
- Reports are self-contained with default statistics and provenance information
- How to choose between HTML (.html) vs ZIP (.zip) formats based on dataset size
- The folder structure of ZIP archives and how to view them in a browser
This aligns well with the documentation updates in
docs/snakefiles/reporting.rst.docs/snakefiles/reporting.rst (6)
13-17: Well-structured new section headingThe new section "Including results in a report" with appropriate restructured text reference tag improves document organization and navigation.
262-264: Helpful metadata clarificationThis addition clearly explains where the metadata for reports comes from, which is valuable for users to understand how Snakemake tracks execution statistics.
265-285: Well-structured new section on HTML reportsThis new section with the appropriate reference tag clearly explains:
- The default command to create a report
- How to customize the report filename
- The limitations of HTML reports for larger workflows
The content is clear and the examples are helpful.
286-301: Clear instructions for ZIP archive reportsThis section effectively explains:
- When to use ZIP archives (for complex reports with many samples)
- How to generate a ZIP archive report
- How to navigate the archive after unpacking
The instructions align well with the CLI help text updates.
303-316: Useful partial reports sectionThis new section provides valuable information about creating reports for specific targets, which helps users:
- Generate reports for incomplete workflows
- Create reports for specific parts of larger workflows
- Generate different reports for alternative target rules
Clear and practical explanation.
317-330: Comprehensive custom layout sectionThis section provides clear instructions for customizing report appearance with:
- How to apply a custom stylesheet
- What can be customized (logo, colors)
- Links to example code and resources
This is a helpful addition for users wanting to personalize their reports.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
cmeesters
reviewed
Mar 10, 2025
Member
cmeesters
left a comment
There was a problem hiding this comment.
Just a few minor suggestions - no need to accept them all.
Co-authored-by: David Laehnemann <david.laehnemann@hhu.de>
|
2 tasks
johanneskoester
pushed a commit
that referenced
this pull request
Mar 11, 2025
🤖 I have created a release *beep* *boop* --- ## [8.30.0](v8.29.3...v8.30.0) (2025-03-11) ### Features * Add extra input size properties ([#2424](#2424)) ([359ae2e](359ae2e)) * shell function calls inside of the 'run' directive now use conda, container, or envmodules specifications ([#2289](#2289)) ([0193e34](0193e34)) * xonsh support for script directive ([#3310](#3310)) ([d1c369b](d1c369b)) ### Bug Fixes * include unit test templates in `setup.py` ([#3362](#3362)) ([b47252c](b47252c)) ### Documentation * clearly explain report rendering to ZIP archive ([#3357](#3357)) ([948e8fb](948e8fb)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This was referenced Mar 11, 2025
kjohnsen
pushed a commit
to kjohnsen/snakemake
that referenced
this pull request
Dec 15, 2025
This addresses the first part of snakemake#3319, by making the explanations of ZIP archive reports better. ### QC <!-- Make sure that you can tick the boxes below. --> * [x] The PR contains a test case for the changes or the changes are already covered by an existing test case. * [x] 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 is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Enhanced the report generation guide with clearer instructions for creating self-contained reports in both HTML and ZIP formats. - Expanded details on report content, including runtime statistics, provenance information, and workflow topology. - Provided additional guidance for custom layouts, annotations, and partial reports. - Updated the help text to offer improved clarity on selecting the optimal report format based on dataset size. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-authored-by: Christian Meesters <cmeesters@users.noreply.github.com>
kjohnsen
pushed a commit
to kjohnsen/snakemake
that referenced
this pull request
Dec 15, 2025
🤖 I have created a release *beep* *boop* --- ## [8.30.0](snakemake/snakemake@v8.29.3...v8.30.0) (2025-03-11) ### Features * Add extra input size properties ([snakemake#2424](snakemake#2424)) ([359ae2e](snakemake@359ae2e)) * shell function calls inside of the 'run' directive now use conda, container, or envmodules specifications ([snakemake#2289](snakemake#2289)) ([0193e34](snakemake@0193e34)) * xonsh support for script directive ([snakemake#3310](snakemake#3310)) ([d1c369b](snakemake@d1c369b)) ### Bug Fixes * include unit test templates in `setup.py` ([snakemake#3362](snakemake#3362)) ([b47252c](snakemake@b47252c)) ### Documentation * clearly explain report rendering to ZIP archive ([snakemake#3357](snakemake#3357)) ([948e8fb](snakemake@948e8fb)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
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
2 participants
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.
This addresses the first part of #3319, by making the explanations of ZIP archive reports better.
QC
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