-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add sphinx.ext.collapse
#10532
base: master
Are you sure you want to change the base?
Add sphinx.ext.collapse
#10532
Conversation
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! 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 |
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
I added support for the A |
I hesitated to add a new directive to Sphinx for some reasons.
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. |
I agree. I think you're referring to |
No. See #10532 (comment) |
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. |
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 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. |
Though wouldn't be immediately useful for CPython. |
sphinx.ext.collapse
sphinx/ext/collapse.py
Outdated
# Same as util.nested_parse_with_titles but try to handle nested | ||
# sections which should be raised higher up the doctree. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 😅
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
Hey all, I have a slightly different solution to propose #12507 🙃 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 |
@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. |
sphinx.ext.collapse
adds support for collapsible content in HTML.Feature or Bugfix
Purpose
<details>
, and it is a useful feature.Relates
cc: @vsajip @EpicWink @ezio-melotti (from the Discuss thread)
(Rendered documentation)
A