Support Markdown parsing inside collapsible blocks <details><summary>…</summary></details>

NumesSanguis commented 4 years ago

Thanks again for m2r2 and I hope it's okay to make requests here?

What I want to do

In my .md file I'm making use of collapsible blocks that makes the document much more readable:

<details><summary>Expand (CLICK ME)</summary>
<p>

Large Markdown formatted text:
- Many lists

</p>
</details>

Which turns on GitHub into:

Expand (CLICK ME)

Large Markdown formatted text: - Many lists

Issue

When turning the above Markdown into HTML with Sphinx, it just becomes a literal string. Checking the output of m2r2 README.md, we can see that everything is wrapped into a raw html wrapper:

.. raw:: html

   <details><summary>Expand (CLICK ME)</summary>
   <p>

   Large Markdown formatted text:
   - Many lists

   </p>
   </details>

Related issue

The problem might be fundamentally the same as encountered by this GitHub Pages user: https://github.community/t/collapsible-markdown-inside-details-summary-summary-details-fails-to-render/10489

The solution for them was to set a different markdown parser: markdown: CommonMarkGhPages

Request / Possible solution

Automatically detect that <details><summary> has been used, and only wrap that part into .. raw:: html OR
Allow to manually specify that m2r2 should parse the contents inside collapsible HTML code OR
Some other approach

CrossNox commented 4 years ago

@NumesSanguis hello again :wave: of course it's ok to ask for requests here! I don't think this should be too complicated using mistune. I'm reserving a time slot for this after wednesday. Mind if i tag you on a PR?

NumesSanguis commented 4 years ago

@CrossNox thank you for taking a look at it! Of course you can tag me. Not sure if I can respond quickly due to time-zone differences though.

NumesSanguis commented 4 years ago

This code worked for me in an .rst document (https://stackoverflow.com/a/60394068):

.. raw:: html

   <details>
   <summary><a>big code</a></summary>

.. code-block:: python

   lots_of_code = "this text block"

.. raw:: html

   </details>

The only caveat is that I have to place <p> before <details> and </p> after </details> to get nice spacing in my documentation with my html_theme = 'sphinx_rtd_theme'.

CrossNox commented 3 years ago

@NumesSanguis sorry this was kept open for so long. I'm not sure this is relevant to you anymore, but if you could test #35 I'd be very grateful. No problem though if you can't/won't :)

NumesSanguis commented 3 years ago

Hi @CrossNox , thank you for taking a look at it. Unfortunately I'm not working on that project anymore, so feel free to do whatever with this issue.

CrossNox / m2r2