✔️ Linting Passed

All linting checks passed. Your pull request is in excellent shape! ☀️

_{Generated for commit: 54489fd. Link to the linter CI: here}

I think I may want to postpone this PR - I've found that sphinx-design can achieve something as nice by only writing rst stuff with minimal tweak of CSS (no complicated HTML/CSS/JS, and thus works even when JS is disabled). You can preview what it looks like in the video below, and here is the diff: new_web_theme..d6a8deb

However I'm kind of having some trouble updating dependencies because of the pandas warning in the new version, and that's why I'm showing the diff in this way. I've thought about merging main into new_web_theme and then update the dependencies... but I'm thinking that git is not able to merge the lock files correctly? So I asked in #28084 (comment) to see if the dependencies can be directly put in main.

So after the dependency problem is solved, and if maintainers like what is shown in the video below, I can just revert the reverting commit d6a8deb and this PR can be continued.

What do you think about this @adrinjalali?

I like the idea, this looks quite good too, and better than having custom js for it.

Re dependencies, @lesteve would know better.

You can update your dependencies in your branch, no need to add them in main.

Add your dependencies to the doc build in:

Add dependencies in the conda section or in the pip section depending where they are available.

Update the dependencies only for your doc build (faster):

python build_tools/update_environments_and_lock_files.py --select-build 'doc$'

There may be conflicts in the lock-files but you can sort them like any other conflicts.

@lesteve Thanks for you reply! As I replied in #28084 (comment), if we do not worry about the conflicts then merging main into new_web_theme would indeed solve my problem.

Why using sphinx-design?

Comparing sphinx-design tabs with my first approach (new_web_theme..54753ce):

• Simplicity: With sphinx-design tabs we can write pure rst for the actual instructions. Either with my previous implementation or with the current scikit-learn implementation we have to write HTML. Also with sphinx-design there is no need to maintain the complicated part of either CSS or JS; only minor tweaks are needed if necessary.
• When JS is disabled: sphinx-design tabs still work because they are CSS-based. My previous implementation would fail to work properly with JS disabled.
• Tab sync: sphinx-design tabs support syncing, which means that if we have another set of OS-dependent instructions on this same page, switching an OS here will automatically switch the OS there. This is not currently used by maybe useful. My previous implementation does not support such usage.
• Automatic OS selection: sphinx-design does support specifying a specific tab to select by default, by in our case the default OS selection have to be determined dynamically. My previous implementation uses JS so this can be achieved.

Why tweaking sphinx-design tabs?

This is in fact personal aesthetics choice. You may take a look at what the original nested tabs of sphinx-design look like in their documentation. I think left-aligned tabs are good if it is not nested. In the nested case the two levels of tabs are of different widths which kind of look weird from my perspective. Also I removed the box shadow at the bottom of the tab contents. Again, I think it is fine for non-nested cases, but we have nested tab sets which leads to double bottom box shadow.

What are the other changes?

There are some changes of wording in the installation instructions, so it would be nice if maintainers can take a look at the instructions under each tab to confirm their correctness. Then some indentation issues that I missed in #28107. Then about sphinx-prompt: there is now support for default modifiers for bash, batch, and powershell. I'm preferring powershell because I think nowadays Windows users use it more than cmd; also it is easier to add comments (powershell uses # same as bash, but in cmd I think one needs to use something like & REM).

So the dependency problem is fixed, sphinx-design is added, and I can go with the sphinx-design tabs approach. Some explanations of the new changes: #28336 (comment). Check the rendered docs here.

@glemaitre @thomasjpfan who also commented in the first PR: would you like to take a look when you have time? 😁