# Python console embedded in docs **URL:** \ **Category:** Documentation\ **Created:** [November 11, 2023, 11:43pm UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477 "2023-11-11T23:43:54Z")\ **Posts on this page:** 13\ **Page:** 1
**Author:** ![maciek](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/maciek/32/596_2.png) [@maciek](https://discuss.python.org/u/maciek)\ **Post date:** [November 11, 2023, 11:43pm UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/1 "2023-11-11T23:43:54Z")
Hi, I wanted to share an idea. The Python documentation contains many code snippets that illustrate the described syntax and behaviours of the language and standard libraries. I think having embedded Python console in the docs to let execute the snippets and play with them, would raise the value of docs for its users. When I think of how it could look like in practice, I see an extra element for the console, similar to a new email composing window in Gmail. A tab or window floating on bottom right of the page. The REPL snippets could have a new action button – “Execute in the console”, which would move the code into the console and execute it live. The console would be a REPL, which would let rerun the commands line by line and modify them. ![Zrzut ekranu 2023-11-12 o 00.16.30](https://us1.discourse-cdn.com/flex002/uploads/python1/original/2X/d/dc94580e2b1c7efcf9afe115a547a46374bcbda9.jpeg) [Pyodide](https://pyodide.org/en/stable/) or [PyScript](https://docs.pyscript.net/2023.11.1/) should be a good fit for this feature. What do you think? ---
**Author:** ![csm10495](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/csm10495/32/9731_2.png) [@csm10495](https://discuss.python.org/u/csm10495)\ **Post date:** [November 12, 2023, 3:43am UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/2 "2023-11-12T03:43:01Z")
I think this would be cool, though some examples may have to be checked since they may depend on earlier examples. Then again this could also easily lead to more load (and potential for security issues) on the hosting. If I just look at it as a user, it’s almost like turning the docs into an IPython notebook and that is cool and useful. ---
**Author:** ![barry-scott](https://avatars.discourse-cdn.com/v4/letter/b/e9c0ed/32.png) [@barry-scott](https://discuss.python.org/u/barry-scott)\ **Post date:** [November 12, 2023, 9:16am UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/3 "2023-11-12T09:16:45Z")
You would need two versions of the doc if this is implemented. One version that is just static web pages that can be packaged for local installation. I do this on macOS and Fedora from the official packages. The other version with the embedded console. ---
**Author:** ![tjreedy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/tjreedy/32/137_2.png) [@tjreedy](https://discuss.python.org/u/tjreedy)\ **Post date:** [November 13, 2023, 4:17am UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/4 "2023-11-13T04:17:13Z")
I have thought about sometime doing something like this by combining pieces of IDLE and turtledemo. Turtledemo has two side-by-side panes – python turtle code in a tk Text window on the left and a turtle canvas on the right. In IDLE, Help =\> IDLE Doc displays a local copy of the IDLE web page in an IDLE read-only subclass of a tk Text widget. I does so by running the html text through a html-to-tk converter that knows enough html for this page. I expect the converter would have to be augmented to display other pages. This would replace the turtledemo Text. This would not require a separate version of the docs. IDLE’s Shell combines a subclass of code.InteractiveInterprer for its logic and a version of IDLE’s Text subclass for its GUI. A version of this would replace the turtle canvas. New glue code to connect the panes would be needed. ---
**Author:** ![maciek](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/maciek/32/596_2.png) [@maciek](https://discuss.python.org/u/maciek)\ **Post date:** [November 14, 2023, 3:22pm UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/5 "2023-11-14T15:22:33Z")
> [@csm10495](#): > > Then again this could also easily lead to more load (and potential for security issues) on the hosting. Pyodide and PyScript base on [WebAssembly](https://webassembly.org/), which is a [widely supported](https://webassembly.org/roadmap/) standard and describes a [memory-safe, sandboxed execution environment](https://webassembly.org/docs/security/). Therefore I don’t really see the potential for security issues. Pyodide could be potentially vendored along with the docs and it also can work offline. Though it is quite big: the full package is 200+MB in size. Downloading the console files should be optional, for saving the bandwidth for users with worse internet connections. ---
**Author:** ![maciek](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/maciek/32/596_2.png) [@maciek](https://discuss.python.org/u/maciek)\ **Post date:** [February 19, 2024, 3:59pm UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/6 "2024-02-19T15:59:01Z")
Pydantic’s docs use a Pyodide-based plugin by @samuelcolvin: - example: [Welcome to Pydantic - Pydantic](https://docs.pydantic.dev/latest/) - source code: [GitHub - samuelcolvin/mkdocs-run-code](https://github.com/samuelcolvin/mkdocs-run-code) Before clicking run: ![docs.pydantic.dev_latest_](https://us1.discourse-cdn.com/flex002/uploads/python1/original/3X/4/2/42258e4be98f995176a5ab3e0a7fcdc7ef19bc09.png) After clicking run: ![docs.pydantic.dev_latest_ (1)](https://us1.discourse-cdn.com/flex002/uploads/python1/original/3X/9/b/9b184e682f71e566283587f5f91f1d8935ed599d.png) ---
**Author:** ![samuelcolvin](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/samuelcolvin/32/6406_2.png) [@samuelcolvin](https://discuss.python.org/u/samuelcolvin)\ **Post date:** [February 20, 2024, 11:25pm UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/7 "2024-02-20T23:25:13Z")
See [GitHub - samuelcolvin/mkdocs-run-code](https://github.com/samuelcolvin/mkdocs-run-code) for how this is implemented. ---
**Author:** ![maciek](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/maciek/32/596_2.png) [@maciek](https://discuss.python.org/u/maciek)\ **Post date:** [April 3, 2024, 9:39pm UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/8 "2024-04-03T21:39:03Z")
I’m looking forward to two PyCon US 2024 talks: - [Making Your Documentation Interactive with PyScript](https://us.pycon.org/2024/schedule/presentation/92/) by @JeffGlass - [Interactive Software Documentation, with PyScript](https://us.pycon.org/2024/schedule/presentation/115/) by Valerio Maggio They can bring valuable input connected with this topic. Also @JeffGlass is an author of the [sphinx\_pyscript](https://sphinx-pyscript.readthedocs.io/en/latest/) package. ---
**Author:** ![JeffGlass](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jeffglass/32/17293_2.png) [@JeffGlass](https://discuss.python.org/u/JeffGlass)\ **Post date:** [April 3, 2024, 9:43pm UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/9 "2024-04-03T21:43:37Z")
Thanks @maciek - we’re looking forward to it as well! Little point - I’m actually not the author of `Sphinx_PyScript`, though I’m hoping to make some contributions there. I am the author of [mkdocs-pyscript](https://github.com/jeffersglass/mkdocs-pyscript), which is similar to the Pydantic docs but leverages PyScript’s ability to run code in worker threads to improve use experience. ---
**Author:** ![hugovk](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hugovk/32/14505_2.png) [@hugovk](https://discuss.python.org/u/hugovk)\ **Post date:** [April 4, 2024, 6:03pm UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/10 "2024-04-04T18:03:40Z")
For comparison, here’s some unofficial release notes for Go which have runnable snippets: > **[Go 1.22: Interactive release notes](https://antonz.org/go-1-22/)** > > Isolated loop variables, range over integers, math/rand v2 and enhanced routing. ---
**Author:** ![willingc](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/willingc/32/20_2.png) [@willingc](https://discuss.python.org/u/willingc)\ **Post date:** [April 8, 2024, 9:33pm UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/11 "2024-04-08T21:33:22Z")
It’s great to see the interactivity in the mkdocs and sphinx ecosystems. The Jupyter community has used [Jupyter Book](https://jupyterbook.org/en/stable/intro.html), nbsphinx, and [mybinder.org](http://mybinder.org) over the years to increase the ability to run code in documentation. Looking forward to the talks at PyCon. ---
**Author:** ![maciek](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/maciek/32/596_2.png) [@maciek](https://discuss.python.org/u/maciek)\ **Post date:** [May 9, 2025, 8:59am UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/12 "2025-05-09T08:59:55Z")
Scientific Python community started an effort on a similar idea: [Scientific Python - SPEC 14 — Interactive Documentation](https://deploy-preview-388--scientific-python-specs.netlify.app/specs/spec-0014/) ([spec PR](https://github.com/scientific-python/specs/pull/388); shared by Hugo). ---
**Author:** ![maciek](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/maciek/32/596_2.png) [@maciek](https://discuss.python.org/u/maciek)\ **Post date:** [October 22, 2025, 4:51pm UTC](https://discuss.python.org/t/python-console-embedded-in-docs/38477/13 "2025-10-22T16:51:38Z")
I’ve published a rudimentary proof of concept using [PyScript](https://docs.pyscript.net/2025.10.1/user-guide/terminal/) (Pyodide underneath) in [a GitHub repo](https://github.com/m-aciek/interactive-docs-poc) and recorded a demo: [![](https://us1.discourse-cdn.com/flex002/uploads/python1/original/3X/8/e/8ed02ac3c981017dc7f4a5e31e2cb185bbfea3f7.jpeg "Interactive Python docs POC 2025-10-22") ](https://www.youtube.com/watch?v=ZBZaR_F6nuA) Current blocker for the project is handling of multiline input like while loops and functions definitions. I’ve modified `copybutton` script to make the buttons send to code to the console. One can experiment with the console using either `document.querySelector("#console").process()` or `document.querySelector("#console").terminal` ([Xterm.js terminal object](https://xtermjs.org/docs/api/terminal/classes/terminal/)) in the developer console. Docs and similar terminal projects: - [Python terminal - PyScript](https://docs.pyscript.net/2025.10.1/user-guide/terminal/) - [Pyodide Console](https://pyodide.org/en/stable/console-v2.html) - [cpython/Tools/wasm/emscripten/web\_example\_pyrepl\_jspi at main · python/cpython · GitHub](https://github.com/python/cpython/tree/main/Tools/wasm/emscripten/web_example_pyrepl_jspi)