# 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.
### Environments
Documentation may benefit from some executable code blocks being isolated from others to create distinct examples. Add the `env` attribute to a fenced code block, using the style of the [attr_list](https://python-markdown.github.io/extensions/attr_list/) markdown plugin, to create an editor for the [PyScript Environment](https://docs.pyscript.net/2024.4.2/user-guide/editor/), e.g. a specific copy of the interpreter isolated from other evnironments.
````
```{.py env="one"}
x = 1
```
```{.py env="one"}
print(x) # Shares an interpreter with the first block
```
```{.py env="two"}
print(x) # Error: 'x' is not defined (in this interpreter)
```
````
### `setup` code
Some demo code snippets may require setup 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 `setup` attribute to a fenced code block with a specific [environment](#Environments), using the style of the [attr_list](https://python-markdown.github.io/extensions/attr_list/) markdown plugin.
````
```{.py setup env="three"}
print("This is some setup code")
```
```{.py env="three"}
print("This is the main tag")
```
````
## 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 `releases/2024.4.2`.
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/2024.2.1"
#Load a snapshot
plugins:
- mkdocs-pyscript:
pyscript_version: "snapshots/2023.11.1.RC3"
```
### `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` in your configuration:
```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": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mkdocs, pyscript",
"author": "Jeff Glass",
"author_email": "glass.jeffrey@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/99/4f/6022147aa01f1eed8efd8b1632abb0f3d5f72f0152a9de3ec9de6acf36fc/mkdocs_pyscript-0.2.0.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### Environments\n\nDocumentation may benefit from some executable code blocks being isolated from others to create distinct examples. Add the `env` attribute to a fenced code block, using the style of the [attr_list](https://python-markdown.github.io/extensions/attr_list/) markdown plugin, to create an editor for the [PyScript Environment](https://docs.pyscript.net/2024.4.2/user-guide/editor/), e.g. a specific copy of the interpreter isolated from other evnironments.\n\n````\n```{.py env=\"one\"}\nx = 1\n```\n\n```{.py env=\"one\"}\nprint(x) # Shares an interpreter with the first block\n```\n\n```{.py env=\"two\"}\nprint(x) # Error: 'x' is not defined (in this interpreter)\n```\n````\n\n### `setup` code\n\nSome demo code snippets may require setup 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 `setup` attribute to a fenced code block with a specific [environment](#Environments), using the style of the [attr_list](https://python-markdown.github.io/extensions/attr_list/) markdown plugin.\n\n````\n```{.py setup env=\"three\"}\nprint(\"This is some setup code\")\n```\n\n```{.py env=\"three\"}\nprint(\"This is the main tag\")\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 `releases/2024.4.2`.\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/2024.2.1\"\n\n#Load a snapshot\nplugins:\n - mkdocs-pyscript:\n pyscript_version: \"snapshots/2023.11.1.RC3\"\n\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` in your configuration:\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.2.0",
"project_urls": {
"Homepage": "https://github.com/jeffersglass/mkdocs-pyscript"
},
"split_keywords": [
"mkdocs",
" pyscript"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7e5571fac33df0a523a35b8fbad7b4285bf3b2f923c893041d8d1fa583adb85d",
"md5": "da237ce05fa071cfbe0d39690cb4e360",
"sha256": "475555960cbe775904523574478842eb6b77ceb33aa2ff8cb0d2ba944f788219"
},
"downloads": -1,
"filename": "mkdocs_pyscript-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "da237ce05fa071cfbe0d39690cb4e360",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17236,
"upload_time": "2024-05-04T16:58:28",
"upload_time_iso_8601": "2024-05-04T16:58:28.981955Z",
"url": "https://files.pythonhosted.org/packages/7e/55/71fac33df0a523a35b8fbad7b4285bf3b2f923c893041d8d1fa583adb85d/mkdocs_pyscript-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "994f6022147aa01f1eed8efd8b1632abb0f3d5f72f0152a9de3ec9de6acf36fc",
"md5": "dcfb1ae894a68805d2f1c60d2c733500",
"sha256": "ddfbf1e94cef03fa550133c7a2457fa56ce9b8ce1c32c014cfec94dfa0c89cb9"
},
"downloads": -1,
"filename": "mkdocs_pyscript-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "dcfb1ae894a68805d2f1c60d2c733500",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16474,
"upload_time": "2024-05-04T16:58:30",
"upload_time_iso_8601": "2024-05-04T16:58:30.604822Z",
"url": "https://files.pythonhosted.org/packages/99/4f/6022147aa01f1eed8efd8b1632abb0f3d5f72f0152a9de3ec9de6acf36fc/mkdocs_pyscript-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-04 16:58:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeffersglass",
"github_project": "mkdocs-pyscript",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mkdocs",
"specs": [
[
">=",
"1.4"
]
]
},
{
"name": "beautifulsoup4",
"specs": [
[
">=",
"4.1"
]
]
}
],
"lcname": "mkdocs-pyscript"
}
JSON
