sphinx
sphinx copied to clipboard
sphinx-doc
Add ``sphinx.ext.collapse``
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)
A
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
Relevant prior art for this: https://github.com/tk0miya/sphinxcontrib-details-directive
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
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).
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.
FWIW, I also lean slightly toward pushing users to use the extension instead of baking this into Sphinx itself.
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?
No. See https://github.com/sphinx-doc/sphinx/pull/10532#issuecomment-1147845664
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
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.
Just moved: https://github.com/sphinx-contrib/sphinxcontrib-details-directive
Let's close this out. We still would want to fix the extension though, since it's borked on the newest Sphinx versions.
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.
https://github.com/python/cpython/pull/111743
Though wouldn't be immediately useful for CPython.
Hey all, I have a slightly different solution to propose #12507 🙃 see: https://sphinx--12507.org.readthedocs.build/en/12507/usage/restructuredtext/directives.html#directive-note
As the author/maintainer of https://sphinx-design.readthedocs.io/en/furo-theme/dropdowns.html, if this was merged, I would in a heartbeat basically deprecate dropdown and push people to use the collapsible option on admonitions
@chrisjsewell from a simplicity POV PR 12507 makes the most sense because having the option integrated under existing admonitions avoids having an additional directive and extension.
Closing in favour of either https://github.com/sphinx-contrib/sphinxcontrib-details-directive or #12507, though the drafted words and tests from this PR may be able to be re-used.
A