docs: switch to sphinx_design for tabs by johanneskoester · Pull Request #3976 · snakemake/snakemake

johanneskoester · 2026-02-18T14:37:11Z

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

Summary by CodeRabbit

Documentation
- Switched docs to a newer tab/design system for more consistent tabbed content and UI.
- Unified and synchronized package-manager tabs for smoother navigation across setup steps.
- Updated OS platform labels for clarity (e.g., MacOS x86_64).
- Renamed a setup step to “Miniforge/Conda environment” and adjusted related labels for consistency.

github-actions · 2026-02-18T14:37:48Z

Please format your code with pixi run format

coderabbitai · 2026-02-18T14:56:00Z

No actionable comments were generated in the recent review. 🎉

📝 Walkthrough

Walkthrough

Migrates Sphinx docs from the sphinx_tabs extension to sphinx_design, converting .. tabs:: markup to .. tab-set::/.. tab-item::, adds sync-group based tab synchronization, updates platform labels, and adjusts a Step 3b heading in setup instructions.

Changes

Cohort / File(s)	Summary
Configuration `docs/conf.py`	Replaced `sphinx_tabs.tabs` with `sphinx_design` in Sphinx extensions.
Documentation Migration `docs/tutorial/setup.rst`	Replaced `.. tabs::`/tab constructs with `.. tab-set::` and `.. tab-item::`; introduced `sync-group` for package-manager/activation/testing sections; updated OS label "MacOS X (x86_64)" → "MacOS (x86_64)"; renamed Step 3b to include "Miniforge/Conda environment."

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

docs: Add pixi setup instructions to general use tutorial #3382: Introduced/used sphinx_tabs-based tab markup that this PR replaces with sphinx_design and tab-set/tab-item conversions.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: switch to sphinx_design for tabs' directly and clearly summarizes the main change: replacing the sphinx_tabs extension with sphinx_design in the documentation configuration and updating tab markup throughout the docs.
Description check	✅ Passed	The PR description follows the required template structure with both QC checklist items completed and checked, indicating test coverage and documentation updates are addressed.
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
Commit unit tests in branch docs/sphinx_design

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: 1

Caution

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

⚠️ Outside diff range comments (1)

docs/tutorial/setup.rst (1)
219-232: ⚠️ Potential issue | 🟡 Minor

"MacOS (x86_64)" label in Step 2 leaves arm64 users without a matching tab.

Step 1b introduces a dedicated MacOS (arm64) tab, but Step 2 only provides MacOS (x86_64). Since the tar command difference is purely Linux vs. macOS (not architecture-dependent), both macOS variants should be covered here. The current label is misleading for arm64 users who just followed the arm64-specific path in Step 1b.

Consider labelling the tab MacOS or MacOS (x86_64/arm64) to signal it covers both architectures:
✏️ Suggested label fix
-    .. tab-item:: MacOS (x86_64)
+    .. tab-item:: MacOS (x86_64/arm64)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/tutorial/setup.rst` around lines 219 - 232, The "MacOS (x86_64)" tab
label is misleading for arm64 users and should be changed to cover both macOS
architectures; update the tab-item label currently defined as "MacOS (x86_64)"
(in the .. tab-item:: entry) to a neutral label such as "MacOS" or "MacOS
(x86_64/arm64)" so it matches the macOS instructions from Step 1b and clarifies
the tar command applies to both architectures.

🤖 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/tutorial/setup.rst`:
- Around line 255-256: The RST section underline for the heading "Step 3b:
Miniforge/Conda environment" is too short; update the underline (the line of
quotation marks directly beneath that title) so it is at least as long as the
title (36 characters) by extending the quotation-mark underline to match the
title length.

---

Outside diff comments:
In `@docs/tutorial/setup.rst`:
- Around line 219-232: The "MacOS (x86_64)" tab label is misleading for arm64
users and should be changed to cover both macOS architectures; update the
tab-item label currently defined as "MacOS (x86_64)" (in the .. tab-item::
entry) to a neutral label such as "MacOS" or "MacOS (x86_64/arm64)" so it
matches the macOS instructions from Step 1b and clarifies the tar command
applies to both architectures.

docs/tutorial/setup.rst

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

docs: switch to sphinx_design for tabs

7e6c2b9

fixes

dc808fb

coderabbitai bot reviewed Feb 18, 2026

View reviewed changes

docs/tutorial/setup.rst Outdated Show resolved Hide resolved

fix

01242e2

johanneskoester merged commit 9674614 into main Feb 18, 2026
160 of 166 checks passed

johanneskoester deleted the docs/sphinx_design branch February 18, 2026 19:00

snakemake-bot mentioned this pull request Feb 18, 2026

chore(main): release 9.17.0 #3977

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: switch to sphinx_design for tabs#3976

docs: switch to sphinx_design for tabs#3976
johanneskoester merged 3 commits intomainfrom
docs/sphinx_design

johanneskoester commented Feb 18, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

github-actions bot commented Feb 18, 2026

Uh oh!

coderabbitai bot commented Feb 18, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

johanneskoester commented Feb 18, 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!

github-actions bot commented Feb 18, 2026

Uh oh!

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

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

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!

1 participant

johanneskoester commented Feb 18, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Feb 18, 2026 •

edited

Loading