ENH: Collapse some code blocks

[larsoner]

Side-remark: It would be really cool if one could specify that individual code sections can be/are folded (or maybe completely omitted?) in sphinx-gallery. This is one of the gallery entries in which only the generated figure is relevant not the code that is generating it.

Originally posted by @timhoffm in https://github.com/matplotlib/matplotlib/issues/22912#issuecomment-1110293857

[timhoffm]

Probably the simplest approach is adding a <details> tag.

closed:

open:

However, styling is not ideal (not sure how far you can improve that with CSS), and I don't think you can change the summary based on collapse state.

[larsoner]

Given that this is something that should ideally be used sparingly, maybe a block-level config that you could use would be good enough like:

# sphinx_gallery_nest_details: Code

Where whatever is after the : says what the summary should be. And we only wrap a given block in details with a summary if this special block-level config shows up.

Another option would be to vendor/add https://github.com/scopatz/hiddencode/blob/master/hidden_code_block.py and then we have full control over how the HTML gets rendered. We could maybe put it together with some variant/derivative/sibling of sphinx-copybutton to have the toggle something inline for example. Then a block-level config like # sphinx_gallery_collapse would tell it to style the code block with the collapse tag, and all other code blocks get collapsibility (but are un-collapsed by default) which might be nice actually. But this is a lot harder...

[timhoffm]

I totally agree with your assessment that inlined collapse buttons would be nicer, but are a lot harder.

What do you think: Would it be possible to start simple and possibly switch out the implementation with something more fancy later? Or would that too breaking for then existing users?

[larsoner]

What do you think: Would it be possible to start simple and possibly switch out the implementation with something more fancy later? Or would that too breaking for then existing users?

I think if we pick a "backend agnostic" SG name for the switch then we're fine, like for example:

# sphinx_gallery_collapse_code

We can start by having this mean "nest the code block in <details>". Later we can add a config value collapse_mode='details' (default) | 'button' where 'button' is my second fancier idea for example, and people can opt into it.

@timhoffm feel free to ping/talk to matplotlib folks to see if anyone is interested in implementing this (or maybe @alexisthual would find it useful, too?), otherwise perhaps @lucyleeow or I could give it a shot at some point (no idea when, though!)

[alexisthual]

Hi sorry I'm a bit late in the game! It's just my opinion, but I usually don't really like collapsing blocks ; it usually feels very clicky to me, and it makes the page's state hard to share (as we probably won't track which blocks are toggled). I think a good option would be to have a toggle/untoggle sticky button which (un)collapses all blocks.

[timhoffm]

Global toggling would not help my use case: There are two kinds of code blocks in examples, one that contains actual relevant code that one want's to communicate to the reader, and one that contains only supporting code to make the example execute. I'd like to be able to hide supporting code block blocks that are more distracting than helpful, on a case-by-case basis.