Add an interactive Demo to Documentation?

[waylan]

Should we add an interactive demonstration to the documentation and if so, what form should it take?

First, some background: Back in 2012 I had created a small one-page site which replicated the demo on daringfireball.net, which is currently hosted at https://waylan.pythonanywhere.com/dingus (I expect that to go away soon and the link will be dead). The old tool used a traditional Python server to accept a POST request and rebuild the page with the rendered Markdown included (the code is preserved here). Recently, I updated the tool to use Pyodide, which runs a Python instance directly in the browser. The new site is a single page app which runs completely in the browser, no server needed once the page is loaded (I have had a local instance running in a browser tab for a week after terminating the dev server). Code is at Python-Markdown/dingus and you can see a demo at https://dingus.python-markdown.workers.dev/.

As I was working on an update to the documentation for this project (#1627) it occurred to me that we could include a demo right in the documentation now that no server component is needed. My question is: what form should the demo be? There are a few options:

1. Copy the existing solution into the docs as-is. This would work but would not match the site's style.
2. Reimplement in the style of the site. We could even use Content Tabs to switch between the source, raw output, and preview.
3. Implement a Python console. Basically, slightly modify Pyodide's example to have it preinstall Python-Markdown and some common extensions (such as PyMdown) so that users can import and run the library in their browser.

I started to build Option 2 as part of #1627, but backed it out as it was getting complicated and makes more sense as a separate PR. My thinking is that I would like to give users the option to play with the config options. The existing solution only allows enabling extensions, but there is no way to set config options. Therefore, I was thinking option 2 could include a fourth tab which provided the user with an editable YAML or JSON file to define all of the keyword arguments to pass into markdown.markdown. But then we would need to build the in-browser code to process and error-handle that along with documentation for is. I also considered just creating a form for all of the options. but that would limit options to what is explicitly implemented. Then it occurred to me that Option 3 was possible. That would let users try writing the code themselves without the need to set up any environment or install any tools. It would also give users the ability to fully customize any option (such as the toc slugify option which accepts a Python callable; a YAML parser would need to be "safe" in this environment and wouldn't be able to support that). The console is sandboxed and users would only be able to import the libraries we preselect (in addition to the list of libs provided by Pyodide by default). The console would also not persist across sessions and therefore would not be sharable by multiple users. We could incorporate a copy-to-clipboard and/or download-to-file button for users to easily save their work and/or copy to a bug report. One thing the console would not do is display an in-browser preview (I am not interested in reimplementing Python-notebook; although, if some already did, that might be a better solution...).

I like Option 3 as we are a library first. Option 3 is directly targeted at developers. And it would encourage bug reports which include console sessions (and therefore would clearly include all config options that the user is using). That said, a significant portion of our users are not Python developers, but users of MkDocs, Zensical and the like. Those users could be intimidated by a console, but might be very comfortable with a YAML/JSON config. Many would likely prefer Options 1 and 2.

One final thought: Yes, we could offer both a console and non-console options, but if we went that route, then my inclination would be to do the console (Option 3) and leave the existing tool at https://dingus.python-markdown.workers.dev/ in place.

Before I spend any more time on Option 2, I thought I would ask for feedback from others. Is there anything obvious I am missing? Or maybe someone knows of a serverless (fully in-browser) Python-Notebook-like-implementation we could incorporate.

[waylan]

There are a bunch of existing notebook and console solutions that use Pyodide listed at https://pyodide.org/en/stable/project/related-projects.html#notebook-environments-ides-and-repls. Maybe one of them would work better for this.

[waylan]

Here is a session using a Pyodide console:

>>> import markdown
Traceback (most recent call last):
  File "<console>", line 1, in <module>
ModuleNotFoundError: No module named 'markdown'
>>> import micropip
>>> micropip.install('markdown')
<coroutine object PackageManager.install at 0x17f5cf0>
>>> import markdown
Traceback (most recent call last):
  File "<console>", line 1, in <module>
ModuleNotFoundError: No module named 'markdown'
>>> await micropip.install('markdown')
>>> import markdown
>>> markdown.markdown('Hello **world**!')
'<p>Hello <strong>world</strong>!</p>'

And here is a screenshot:

In contrast, here is a session using Starboard (more info here):

>>> import micropip
>>> micropip.install('markdown')
>>> import markdown
>>> markdown.markdown('Hello **world**!')
<p>Hello <strong>world</strong>!</p> 

And here is a screenshot:

Starboard looks promising, but there is almost no publicly available documentation.

[facelessuser]

I like Pyodide and use it for live demos and such in another project: https://facelessuser.github.io/coloraide/. I'm all for using it in Python Markdown.

[waylan]

Ah, you already have that deployed in a Zensical site. Did you use a preexisting package or did you custom craft that? Either way, it should be less work to port that into our docs, if that's okay with you.

[facelessuser]

It depends on what exactly you want. I imagine whatever Python Markdown needs is far simpler than what I have on that site. You can run arbitrary code, it intercepts the AST to find color objects, and renders them in specific ways, etc.

Related to Markdown though, I do have a page where you can point it at arbitrary Markdown gists (an example), as I wanted to write and render arbitrary documents on color specific topics I was working on. So in our playground, we already have Python Markdown available in Pyodide, and you can actually import and play with Python Markdown. Though it's locked to whatever version I currently shipped it with.

If we just want a singular, simple demo page, I imagine we can get away with something far simpler, but we could leverage some of this stuff if it made sense.