✔️ Linting Passed

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

_{Generated for commit: 5761a2b. Link to the linter CI: here}

Why using the sphinx-design directive?

I did try to tweak the CSS of our current implementation to achieve a nice visual effect, but the current implementation is after all a hack. If you look closely at the generated HTML there are all those empty p tags caused by the browser auto fixing I closed tags. Using a directive is the more "sphinx" way of doing things from my perspective, and easier to maintain.

Why all those changes to the doc files?

The topic directive is not allowed to be nested in other directives, e.g. dropdowns. Moreover, I believe we do not really mean "topic" in those cases; instead we just want a bold title. Rubrics might be better in this case. And for consistency, I made all the "examples" and "references" into rubrics, thus all those changes.

Why generating dropdown anchors statically instead of using JS?

First JS could be disabled, then the anchors will not work. Second this is tweaking HTML instead of something dynamic on the website that only JS can do. Overall I think it is worth trading build time for this.

Thanks for your quick reply @ArturoAmorQ I will address your comments asap.

One discussion we had here, is how to make firefox be able to find content inside the dropdowns when they're not collapsed? Or how to have an easy way to collapse all drop downs.

Ah I've never noticed that <details> is not supported by all browsers (if I did not misunderstand what you are saying). Then an easy alternative might be to use an additional extension sphinx-togglebutton which uses JavaScript instead of <details>.

If I misunderstood could you please specify a bit more or point me to related discussions?

Yes, that's what I mean I think. I'd be okay with the extension. But with the extension, I can't see if it allows users to collapse everything at once.

Can you specify why this is needed? And I think refreshing the page collapses all dropdowns.

For two reasons:

• be able to read the page w/o having to collapse everything
• be able to search in the page, as is, search (in firefox) doesn't find content inside the drop downs.

I see. So I experimented with Chrome, Edge, and Firefox, it seems like:

• They all cannot look into the JavaScript dropdown (based on Bootstrap collapse) when it is hidden;
• Firefox cannot look into <details> when it is not opened while the other two can.

For both JavaScript dropdown and <details> we can create links to collapse/expand all with just a few lines of JavaScript; perhaps we can put it/them in the secondary sidebar when there are dropdowns in the page? One other concern is when JavaScript is disabled:

• With sphinx-togglebutton it will directly show all content when JavaScript is disabled so no problem;
• With sphinx-design I don't see a good way to open all <details> when JavaScript is disabled (but after all this is a corner case I think?)

I don't mind not having a way to open all dropdowns when JS is disabled.

And we should probably use <details> since other browsers can search into them.

I agree, so we stick to sphinx-design dropdowns. However, I'm not sure how to integrate this functionality into the theme. Candidates in my mind are:

• An icon in the top navbar (but I haven't found an icon that is informative enough yet);
• A component in the secondary sidebar saying "Hide/Show all dropdowns";
• A keyboard shortcut to trigger.

WDYT or is there a better idea?

how hard would it be to add something to each drop down, the default one expands the drop down, there could be another one to collapse all, I'm really not sure which one is better.

This is a nice idea, and it would not be too hard. But I tried a bit and failed to find a good icon to represent its meaning. For instance, something like the following is not very informative and looks a bit strange:

Do you have any recommendation, or maybe we can directly use text description? (In that case we need to make sure the text is not mistaken as the description for the original icon.)

On the other hand, after second thought I think there may be another possible solution. When hovering on any dropdown we show a floating button like this for a few seconds (only the chevrons are clickable):

Emm but this also does not look that good... and maybe it is a bit too noisy?

I quite like your first idea, I think those icons look self explanatory enough, and with a hint on hover it would be quite nice.

I agree with @adrinjalali that the first idea is very good:

If you can make tooltips so that when we hover on them it explains what's going on, it would work well.

@Charlie-XIAO , you seem to have a nice feeling for web-based UX. It's a pleasure to see this!

Thanks for your suggestions @adrinjalali @GaelVaroquaux! I implemented something like follows:

I looked quickly at the generated page and I find the solution super neat. I plan to review some the PST PR this week. But the rendering of this one is good.

I updated the logic of sphinxext/dropdown_anchors.py in 5c47c2c. Previously I inserted the anchor after the first text node, but then it would not work for the following case. The new logic inserts the anchor as the third last element (see the comment in that file).

The CI is red because of the following sphinx warning:

Sphinx Warnings in affected files

    doc/modules/gaussian_process.rst:489: WARNING: duplicate citation RW2006, other instance in
    doc/auto_examples/gaussian_process/plot_gpr_co2.rst 

The sphinx warning is strange: indeed there are multiple RW2006 but they are not in the same page, and there are plenty of other RW2006 around that do not cause such a warning. Perhaps I'm misunderstanding how explicit citation in rst works...

Regardless, using a footnote instead would be a simple workaround.

Merging since CI is green.