Making use of the HTML summary/details tag
(too old to reply)
Michael Gielda
2017-08-06 13:40:10 UTC
Hi all,

While browsing some markdown documentation on GitHub (p
<https://github.com/egoist/poi>oi, to be exact) I stumbled upon the use of
the summary/details tags
<https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details> which
made a lot of sense to show some content that does not necessarily need to
be expanded by default but may be interesting to some.

It's the kind of feature that is very natural to documentation: by default
you'd like your docs to mention all possible stuff that may be important
but at the same time be concise enough so that people don't get bored while
reading it. Being able to hide some elements by default is exactly the key
to achieving both.

Would adding a "summary" directive leveraging this HTML functionality (the
PDF and other format fallback could just show the entire thing) make sense?
I know it does not work in IE, but at worst, the relevant theme could
include a polyfill.

I would imagine something like:

.. summary:: Installing in Linux

sudo apt-get install my_package

Alternatively, perhaps we could (optionally) allow some other elements to
be output as summary/details?

Best regards,
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.