[WIP] Add <details> directive to Sphinx extension

[felixfontein]

This allows to write:

.. ansible-details::

    Some RST content to hide by default.

or

.. ansible-details:: A title to show instead of 'Details'

    Some RST content to hide by default.

to create <details> with optional <summary> (the title) (ref).

Currently contains #281, I can rebase when needed. The new stuff is all in c43305a.

[webknjaz]

Why not use an existing extension for this? Like something from https://sphinx-design.rtfd.io/en/furo-theme/dropdowns.html, or https://sphinx-togglebutton.rtfd.io/en/latest/, or https://sphinx-toolbox.rtfd.io/en/stable/extensions/collapse.html.

[felixfontein]

Why not use an existing extension for this? Like something from https://sphinx-design.rtfd.io/en/furo-theme/dropdowns.html, or https://sphinx-togglebutton.rtfd.io/en/latest/, or https://sphinx-toolbox.rtfd.io/en/stable/extensions/collapse.html.

When we were discussing this in the docs meeting, we couldn't find something IIRC. That's why I decided to try this out.

https://sphinx-togglebutton.rtfd.io/en/latest/ only works with JS, which is why I would not use this.

Both https://sphinx-design.readthedocs.io/en/furo-theme/dropdowns.html and https://sphinx-toolbox.readthedocs.io/en/stable/extensions/collapse.html#directive-collapse look good though. I guess we need to find out how the styling works - the second one seems to do a similar thing than this PR, the first as well but might also provide CSS (that's to be verified).

[samccann]

Exercising the existing options listed above. This is what it looks like with sphinx_toolbox.collapse:

And when you expand it...

(probably not a good example of where we'd use this functionality, but it was a quick one I could show in an experiment)

[samccann]

Ok this one shows both extensions in action. The first one (step 2) is sphinx_toolbox.collapse. Step 3 is sphinx_design.

And both expanded:

The text 'Example' can be changed on each use. I'm personally partial to the first one as I find it less visually invasive over the second one. But maybe if we are adding expand/collapse we want it 'in your face' obvious we've hidden something?

[webknjaz]

I'm personally partial to the first one as I find it less visually invasive over the second one.

(A little bit of context)

Note that the current ansible theme is rather poor style-wise. It isn't really accessible, nor is it designed for diverse browsing environments. This extension is created by ExecutableBooks — folks coming from the scientific world that also created MyST (a markdown superset that is possible to use with Sphinx) and they also collaborate on Furo (undoubtfully the best Sphinx theme to date).
I'm pretty sure their design takes into account a lot of things and it objectively looks nice.
And I think that it may feel like their default design doesn't match ours exactly because there's a big difference between the quality of the themes.

But maybe if we are adding expand/collapse we want it 'in your face' obvious we've hidden something?

Probably yes. UX-wise, it should be obvious when some things are clickable/expandable. But either way, any of these solutions should be easily customizable with CSS.

[webknjaz]

Oh, and I forgot to mention the existence of https://sphinx-panels.rtfd.io/en/latest/#dropdown-usage. cc @pradyunsg could you remind me which one has the best interoperability w/o JS? I seem to recall you mentioned one.

[webknjaz]

@felixfontein not sure if you know but the Write The Docs community has a Slack instance with a #sphinx channel in it — it's often a great place to ask about various aspects of the Sphinx setup.
FYI. https://www.writethedocs.org/slack/

[samccann]

Example with sphinx_panels -

and expanded -

Both sphinx_panels and sphinx_design use the same directive dropdown. This suggests to me we could switch from one to the other in the future if we wanted to. Both have the more obvious UI to say 'click here cuz something is hidden'.

[webknjaz]

FWIW I vote for sphinx-design, particularly because it comes from the community with a track record of maintaining their libs.

[felixfontein]

Oh, and I forgot to mention the existence of https://sphinx-panels.rtfd.io/en/latest/#dropdown-usage. cc @pradyunsg could you remind me which one has the best interoperability w/o JS? I seem to recall you mentioned one.

All except https://sphinx-togglebutton.rtfd.io/en/latest/ work fine without JS. (I browse with JS disabled by default, so I'm always testing that first ;-) )

[felixfontein]

Both sphinx-panels and sphinx-design looks good to me. The docs on sphinx-design say: "This package arose as an iteration on sphinx-panels, with the intention to make it more flexible, easier to use, and minimise CSS clashes wth sphinx themes." (https://sphinx-design.readthedocs.io/en/furo-theme/get_started.html#migrating-from-sphinx-panels). So I second @webknjaz, let's use that one!

[webknjaz]

Ref: ansible-community/sphinx_ansible_theme#39

[felixfontein]

Closing since the PR itself is no longer needed, and the contents are tracked in other places.