Add sphinx.ext.collapse

[AA-Turner]

sphinx.ext.collapse adds support for collapsible content in HTML.

Feature or Bugfix

• Feature

Purpose

• There have been several requests for support of <details>, and it is a useful feature.

Relates

• https://discuss.python.org/t/adopting-the-diataxis-framework-for-python-documentation/15072/43?u=aa-turner

cc: @vsajip @EpicWink @ezio-melotti (from the Discuss thread)

(Rendered documentation)

A

[AA-Turner]

Screenshots:

Note that both the summary line and the body are parsed as reStructuredText, and the body can have sections etc.

reST source used:

Collapsible directive tests
===========================

.. collapsible::

   Default section summary line

.. collapsible:: Custom summary line for the collapsible content

   Collapsible sections can also have custom summary lines

.. collapsible::

   Collapsible sections can have normal reST content such as **bold** and
   *emphasised* text, and also links_!

   .. _links: https://link.example/

.. collapsible::

   Collapsible sections can have sections:

   A Section
   ---------

   Some words within a section, as opposed to outwith the section.

.. collapsible:: Summary text here with **bold** and *em* and a :rfc:`2324`
                 reference! That was a newline in the reST source! We can also
                 have links_ and `more links <https://link2.example/>`__.

   This is some text!

Output HTML

Output HTML (expanded)

A

[pradyunsg]

Relevant prior art for this: https://github.com/tk0miya/sphinxcontrib-details-directive

[AA-Turner]

That would have saved ... a lot of work! More the fool for not looking if this had been implemented before. I'll look through and see if there's anything @tk0miya implemented that I haven't.

A

[vsajip]

That would have saved ... a lot of work! More the fool for not looking

Not at all, and thanks for looking at this, Adam! I wasn't aware of that extension, either. Perhaps a review should be done of other sphinxcontrib extensions like this to see if they would benefit from folding into Sphinx itself, so that everyone benefits without having to know about available extensions etc. (I guess they're not well-enough known to the wider community).

[vsajip]

My few comments here are on the feature itself rather than the implementation. Perhaps it would be useful to compare and contrast with the sphinxcontrib "details" extension (e.g. incorporating an "open" flag option). Of course, that extension remains useful for older Sphinx versions, which is perhaps why it was developed as such.

[AA-Turner]

I added support for the :open: flag.

A

[tk0miya]

I hesitated to add a new directive to Sphinx for some reasons.

• About dialect. This will make the difference in the reST between docutils and Sphinx larger. I know reST allows to enhance its syntax via directives and roles. But I prefer to keep them almost the same as possible. If you think the collapsible content is important, how about proposing this to the docutils?
• About output format. I consider the principle of reST and Sphinx as "single input, multiple outputs". So it's not better to add a notation only for HTML.

This is why I created sphinxcontrib-details as an extension and not created as a built-in feature.

[pradyunsg]

FWIW, I also lean slightly toward pushing users to use the extension instead of baking this into Sphinx itself.

[EpicWink]

FWIW, I also lean slightly toward pushing users to use the extension instead of baking this into Sphinx itself.

I agree. I think you're referring to sphinx-design?

[pradyunsg]

No. See #10532 (comment)

[AA-Turner]

Ok, if we don't go ahead with this we should at least improve documentation to suggest extensions. @tk0miya would you consider moving your extension to @sphinx-contrib to make it more discoverable / 'official'?

A

[tk0miya]

What do you mean "official"? I'm okay to move the repo to the sphinx-contrib org. But I don't think it does not mean the extension is an "official" extension.

[tk0miya]

Just moved: https://github.com/sphinx-contrib/sphinxcontrib-details-directive

[pradyunsg]

Let's close this out. We still would want to fix the extension though, since it's borked on the newest Sphinx versions.

[electric-coder]

I've been using sphinx-design to get details (linked above) and there's also sphinx-toolbox which also works well.

While it'd be nice to have this integrated in Sphinx core I don't think it's a priority since there are viable alternatives.

[AA-Turner]

python/cpython#111743

Though wouldn't be immediately useful for CPython.

[chrisjsewell]

I have to say I'm completely against this kind of "hacking" into docutils.
If you want to do something like this, then either it needs to be upstreamed to docutils, or it needs much, much more testing than is in this PR.
simple example: what happens if you put your collapse directive inside a note directive?

Not only is it already brittle in rst, but also its definitely not supported by myst 😅

[chrisjsewell]

I certainly get the desire to have nested parsing with sections (in fact I am trying to achieve it in https://sphinx-rust.readthedocs.io)

but this should be a "core" function within sphinx/docutils, with good testing, rather than having multiple implementations scattered across the code base