Run PythonCode on a docu side

[CesMak]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

• ... to my best knowledge, my idea wouldn't break something for other users
• ... the documentation does not mention anything about my idea
• ... there are no open or closed issues that are related to my idea

Description

Being able to run small python programs within a mkdocs material page would have many advantages:

• it would be possible to have e.g. plots that are configurable with some math behind.
• the docu pages would be more reactive and probably more fun to browse.

Using python scripts in mkdocs pages I think it would be possible to use: https://pyscript.net/
Is there any docu yet available - or are similar approaches planned? (I did not find any until now)

Use Cases

• it would be possible to have e.g. plots that are configurable with some math behind.
• the docu pages would be more reactive and probably more fun to browse.

Screenshots / Mockups

No response

[squidfunk]

There are several users already doing this, e.g. @facelessuser. As I understand, this can be pulled off with custom fences. However, it is beyond the scope of this project. Implementation is left to the author.

[facelessuser]

Yes, it is certainly possible to run Python code in Material, but it requires a bit of work. PyScript, IIRC, is a wrapper around Pyodide. I don't currently use PyScript, but instead use Pyodide directly, coupled with SuperFences, to achieve live, interactive Python "playgrounds".

In this example you can edit the code blocks and run them. On submission, if not already loaded, we use Pyodide to initialize the required Python wheels. This is best used in conjunction with Material's instant loading so we don't have to keep initializing, though there are still some corner cases Material doesn't properly instant load on (xlink:href), but maybe Material can one day handle those properly.

On submission, we send the user edited payload to be executed by our script which returns a REPL style output showing the results. We do have a bit of special logic to recognize certain text output (for color) and recognize certain objects (color interpolation objects, color objects, etc.) to provide color previews.

What you want is probably something like Jupyter, though I'm not sure how nice it plays with the Material theme. Obviously, what I describe that I use above is a bit more simplistic. I had a very focused goal of simply creating basic REPL playgrounds, the only additional, advanced logic I wanted was color previews. Could this be more generalized? Possibly.

There is this plugin though too: https://pawamoy.github.io/markdown-exec/#configuration. It could be configured in such a way as above to take and run live on a document site using SuperFences and export results.

This is all advanced stuff though. And certainly, nothing is stopping you from just doing your own PyScript implementation for your personal docs as well.

I've considered at least looking into generalizing the "playground" work I've done and some kind of generic SuperFence custom fence that could be used to execute Python and output REPL style outputs. Currently, the plan would be to simply take user-edited content and create REPL-like outputs with the results. Intercepting advanced outputs to generate and export graphs, images, and arbitrary HTML is a bit beyond the scope of my goals as my current focus was more on creating simple interactive examples for some of my Python library's documentation, but I'm sure there could be some export functions created that could do something like this if one was interested. You would essentially create a toolbox of export functions to dump generated content the way you want in some kind of result box after the code block.

Anyways, I have absolutely no timeline for this, and this is just something I'm considering as I have a mild interest in adding interactive playgrounds in a few of my other projects. But there are other options out there that may get you to were you want, but running it live may require a little work on your part unless someone comes up with some pre-packaged way to do so outside of Jupyter, though Jupyter is possibly still an option, but there may be some styling issues that you need to resolve.

[squidfunk]

Thanks, @facelessuser!

[dhirschfeld]

In the sphinx world there is now https://jupyterlite-sphinx.readthedocs.io/en/latest/directives/replite.html which seems pretty slick.