# mkdocs-pyscript
`mkdocs-pyscript` is a plugin for [mkdocs](https://mkdocs.org/) that allows you to transform [code blocks](https://www.mkdocs.org/user-guide/writing-your-docs/#fenced-code-blocks) into executable Python scripts that run in the user's browser, with no backend server, using [PyScript](https://github.com/pyscript/pyscript).
## Installation
Install the plugin into your environment using `pip`, or your favorite environment manager that ues PYPI:
```sh
pip3 install mkdocs-pyscript
```
Enable the plugin by adding it to `mkdocs.yaml`:
```
plugins:
- mkdocs-pyscript
```
## Usage
With this plugin enabled, all Python [fenced code blocks](https://www.mkdocs.org/user-guide/writing-your-docs/#fenced-code-blocks) (type `py` or `python` or any other label that maps to `lang-python`) will have an added LOAD button in the lower-right corrner. When clicked, the code block will be transformed into an editable code snippet (using [codemirror](https://codemirror.net/)). When the user clicks on the green "run" arrow in the lower right corner, or pressed SHIFT+ENTER when focused, will run the inner Python code using PyScript.
The included code is run in a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers), so as not to block the main thread. Each snippet is run in a separate web worker; variables, objects, and names are not shared between executions of the same cell.
### `pre` and `post` code
Some demo code snippets may require setup and/or teardown code to properly function, which don't necessarily need to be displayed to the user. To run a chunk of Python code before any code the user runs in a particular code editor, add the `.py-pre` class to a fenced code block immediately before the user-visible code block, using the style of the [attr_list](https://python-markdown.github.io/extensions/attr_list/) markdown plugin. To run a chunk of code after a user runs a particular code editor add the `.py-post` class to a fenced code block immediately after the user-visible code block:
````
```{.py .py-pre}
print("This is some pre-code")
```
```py
print("This is the main tag")
# Only this code will be displayed in the code editor
```
```{.py .py-post}
print("This is some post code")
```
````
## Configuration
`mkdocs-pyscript` supports options that can be set in `mkdocs.yaml` to control the behavior of the plugin
### `pyscript_version`
The `pyscript_version` property of the plugin controls the version of PyScript that is loaded. If not specified, the current default version is `snapshots/2023.09.1.RC2`.
To support both pre-release snapshots and released versions of PyScript, the provided value is inserted into the following string:
```py
SCRIPT = f'https://pyscript.net/{pyscript_version}/core.js'
```
That is, to load a specific release or snapshot, use:
```yaml
#Load a release
plugins:
- mkdocs-pyscript:
pyscript_version: "releases/2023.11.1"
#Load a snapshot
plugins:
- mkdocs-pyscript:
pyscript_version: "snapshots/2023.11.1.RC3"
#Load the most recent (unstable) build:
plugins:
- mkdocs-pyscript:
pyscript_version: "unstable"
```
### `selective`
By default, `mkdocs-pyscript` turns *all* blocks with type `py` or `python` into exectuable code snippets. To cause only selected blocks to be transformed:
1. Set the `selective` property to `true`:
```yaml
plugins:
- mkdocs-pyscript:
selective: true
```
2. Specify `.pyscript` as an additional class for the codeblocks that you want to be runnable:
````py
```{.py .pyscript}
print("Hello, world!")
```
````
Raw data
{
"_id": null,
"home_page": "https://github.com/jeffersglass/mkdocs-pyscript",
"name": "mkdocs-pyscript",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "mkdocs,pyscript",
"author": "Jeff Glass",
"author_email": "mail@jeff.glass",
"download_url": "https://files.pythonhosted.org/packages/ff/2e/7ba870a4ecb94e0b2e118cc7ddb14843f307b91b8f9aa49c952b0ae2a78c/mkdocs-pyscript-0.1.1.tar.gz",
"platform": null,
"description": "# mkdocs-pyscript\n`mkdocs-pyscript` is a plugin for [mkdocs](https://mkdocs.org/) that allows you to transform [code blocks](https://www.mkdocs.org/user-guide/writing-your-docs/#fenced-code-blocks) into executable Python scripts that run in the user's browser, with no backend server, using [PyScript](https://github.com/pyscript/pyscript).\n\n## Installation\n\nInstall the plugin into your environment using `pip`, or your favorite environment manager that ues PYPI:\n\n```sh\npip3 install mkdocs-pyscript\n```\n\nEnable the plugin by adding it to `mkdocs.yaml`:\n\n```\nplugins:\n - mkdocs-pyscript\n```\n\n## Usage\n\nWith this plugin enabled, all Python [fenced code blocks](https://www.mkdocs.org/user-guide/writing-your-docs/#fenced-code-blocks) (type `py` or `python` or any other label that maps to `lang-python`) will have an added LOAD button in the lower-right corrner. When clicked, the code block will be transformed into an editable code snippet (using [codemirror](https://codemirror.net/)). When the user clicks on the green \"run\" arrow in the lower right corner, or pressed SHIFT+ENTER when focused, will run the inner Python code using PyScript.\n\nThe included code is run in a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers), so as not to block the main thread. Each snippet is run in a separate web worker; variables, objects, and names are not shared between executions of the same cell.\n\n### `pre` and `post` code\n\nSome demo code snippets may require setup and/or teardown code to properly function, which don't necessarily need to be displayed to the user. To run a chunk of Python code before any code the user runs in a particular code editor, add the `.py-pre` class to a fenced code block immediately before the user-visible code block, using the style of the [attr_list](https://python-markdown.github.io/extensions/attr_list/) markdown plugin. To run a chunk of code after a user runs a particular code editor add the `.py-post` class to a fenced code block immediately after the user-visible code block:\n\n````\n```{.py .py-pre}\nprint(\"This is some pre-code\")\n```\n\n```py\nprint(\"This is the main tag\")\n# Only this code will be displayed in the code editor\n```\n\n```{.py .py-post}\nprint(\"This is some post code\")\n```\n````\n\n## Configuration\n\n`mkdocs-pyscript` supports options that can be set in `mkdocs.yaml` to control the behavior of the plugin\n\n### `pyscript_version`\n\nThe `pyscript_version` property of the plugin controls the version of PyScript that is loaded. If not specified, the current default version is `snapshots/2023.09.1.RC2`.\n\n\nTo support both pre-release snapshots and released versions of PyScript, the provided value is inserted into the following string:\n\n```py\nSCRIPT = f'https://pyscript.net/{pyscript_version}/core.js'\n```\n\nThat is, to load a specific release or snapshot, use:\n```yaml\n#Load a release\nplugins:\n - mkdocs-pyscript:\n pyscript_version: \"releases/2023.11.1\"\n\n#Load a snapshot\nplugins:\n - mkdocs-pyscript:\n pyscript_version: \"snapshots/2023.11.1.RC3\"\n\n#Load the most recent (unstable) build:\nplugins:\n - mkdocs-pyscript:\n pyscript_version: \"unstable\"\n```\n\n### `selective`\n\nBy default, `mkdocs-pyscript` turns *all* blocks with type `py` or `python` into exectuable code snippets. To cause only selected blocks to be transformed:\n\n 1. Set the `selective` property to `true`:\n```yaml\nplugins:\n - mkdocs-pyscript:\n selective: true\n```\n 2. Specify `.pyscript` as an additional class for the codeblocks that you want to be runnable:\n\n````py\n```{.py .pyscript}\nprint(\"Hello, world!\")\n```\n````\n",
"bugtrack_url": null,
"license": "APACHE",
"summary": "Add PyScript to your mkdocs site",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/jeffersglass/mkdocs-pyscript"
},
"split_keywords": [
"mkdocs",
"pyscript"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "971644bf0df92d3b9f7717e569ae0e3c0faadfc98047ea89bf670c1798e59af7",
"md5": "a5aff76d8795eaa82e50f42922aa6f40",
"sha256": "e97c14165c9ac86edc1b161819c1bffab45b1d8490bbebf06749d35ce9504a25"
},
"downloads": -1,
"filename": "mkdocs_pyscript-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a5aff76d8795eaa82e50f42922aa6f40",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 235455,
"upload_time": "2023-11-07T00:24:28",
"upload_time_iso_8601": "2023-11-07T00:24:28.161906Z",
"url": "https://files.pythonhosted.org/packages/97/16/44bf0df92d3b9f7717e569ae0e3c0faadfc98047ea89bf670c1798e59af7/mkdocs_pyscript-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ff2e7ba870a4ecb94e0b2e118cc7ddb14843f307b91b8f9aa49c952b0ae2a78c",
"md5": "4c16e932b1d1c961d2b8f54aff18bec1",
"sha256": "61fffbe0c5b3d0282f3da0911b29c2d257aa5f93c41322c24bd9a101fdcbf892"
},
"downloads": -1,
"filename": "mkdocs-pyscript-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "4c16e932b1d1c961d2b8f54aff18bec1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 233691,
"upload_time": "2023-11-07T00:24:31",
"upload_time_iso_8601": "2023-11-07T00:24:31.912133Z",
"url": "https://files.pythonhosted.org/packages/ff/2e/7ba870a4ecb94e0b2e118cc7ddb14843f307b91b8f9aa49c952b0ae2a78c/mkdocs-pyscript-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-07 00:24:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeffersglass",
"github_project": "mkdocs-pyscript",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "mkdocs-pyscript"
}
JSON
