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.
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.
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, which is similar to the Pydantic docs but leverages PyScript’s ability to run code in worker threads to improve use experience.
It’s great to see the interactivity in the mkdocs and sphinx ecosystems. The Jupyter community has used Jupyter Book, nbsphinx, and mybinder.org over the years to increase the ability to run code in documentation. Looking forward to the talks at PyCon.
