From ee2f46cfb93fadfcb2070267c9dc9ddaf76a2cb2 Mon Sep 17 00:00:00 2001 From: Madhur Tandon <20173739+madhur-tandon@users.noreply.github.com> Date: Tue, 6 Dec 2022 19:26:19 +0530 Subject: [PATCH] split py-config into sections (#1022) * split into sections * new section about custom keys * link to fetch section * add example for using runtime --- docs/reference/elements/py-config.md | 55 ++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 12 deletions(-) diff --git a/docs/reference/elements/py-config.md b/docs/reference/elements/py-config.md index 7a4a275b..185dde89 100644 --- a/docs/reference/elements/py-config.md +++ b/docs/reference/elements/py-config.md @@ -15,14 +15,18 @@ The `` element should be placed within the `` element. ## Examples -### `` using TOML (default) +### Defining an inline config + +- `` using TOML (default) + ```{note} -Reminder: when using TOML, any Arrays of Tables defined with double-brackets (like `[[runtimes]]` and `[[fetch]]` must come after individual keys (like `paths = ...` and `packages=...`) +Reminder: when using TOML, any Arrays of Tables defined with double-brackets (like `[[runtimes]]` and `[[fetch]]` must come after individual keys (like `plugins = ...` and `packages=...`) ``` ```html - autoclose_loader = true + [splashscreen] + autoclose = true [[runtimes]] src = "https://cdn.jsdelivr.net/pyodide/v0.21.2/full/pyodide.js" @@ -31,12 +35,14 @@ Reminder: when using TOML, any Arrays of Tables defined with double-brackets (li ``` -### JSON config using the `type` attribute. +- `` using JSON via `type` attribute ```html { - "autoclose_loader": true, + "splashscreen": { + "autoclose": true + }, "runtimes": [{ "src": "https://cdn.jsdelivr.net/pyodide/v0.21.2/full/pyodide.js", "name": "pyodide-0.21.2", @@ -46,7 +52,9 @@ Reminder: when using TOML, any Arrays of Tables defined with double-brackets (li ``` -### Use of the `src` attribute: +### Defining a file based config + +- Use of the `src` attribute ```html @@ -54,14 +62,17 @@ Reminder: when using TOML, any Arrays of Tables defined with double-brackets (li where `custom.toml` contains ```toml -autoclose_loader = true +[splashscreen] +autoclose = true + [[runtimes]] src = "https://cdn.jsdelivr.net/pyodide/v0.21.2/full/pyodide.js" name = "pyodide-0.21.2" lang = "python" ``` -### JSON using the `type` and `src` attribute. +- JSON using the `type` and `src` attribute + ```html ``` @@ -69,7 +80,9 @@ where `custom.json` contains ```json { - "autoclose_loader": true, + "splashscreen": { + "autoclose": true, + }, "runtimes": [{ "src": "https://cdn.jsdelivr.net/pyodide/v0.21.2/full/pyodide.js", "name": "pyodide-0.21.2", @@ -78,7 +91,7 @@ where `custom.json` contains } ``` -### Expanding with inline configuration +### Mixing inline and file based configs One can also use both i.e pass the config from `src` attribute as well as specify it as `inline`. So the following snippet is also valid: @@ -109,6 +122,8 @@ This is helpful in cases where a number of applications share a common configura The keys supplied through `inline` override the values present in config supplied via `src`. +## Dependencies and Packages + One can also declare dependencies so as to get access to many 3rd party OSS packages that are supported by PyScript. You can also link to `.whl` files directly on disk like in our [toga example](https://github.com/pyscript/pyscript/blob/main/examples/toga/freedom.html). @@ -183,7 +198,8 @@ def make_x_and_y(n): ``` In the HTML tag ``, paths to local modules are provided in the -`files` key within the `fetch` section. +`files` key within the `fetch` section. Refer to the [fetch](#fetch) section for +more details. ```html @@ -232,7 +248,7 @@ The following optional values are supported by ``: | `plugins` | List of Plugins | List of Plugins are to be specified here. The default value is an empty list. | | `runtimes` | List of Runtimes | List of runtime configurations, described below. The default value contains a single Pyodide based runtime. | -### Fetch +### Fetch A fetch configuration consists of the following: | Value | Type | Description | @@ -253,6 +269,21 @@ A runtime configuration consists of the following: | `name` | string | Name of the runtime. This field can be any string and is to be used by the application author for their own customization purposes | | `lang` | string | Programming language supported by the runtime. This field can be used by the application author to provide clarification. It currently has no implications on how PyScript behaves. | +#### Example + +- The default runtime is `pyodide`, another version of which can be specified as following + +```html + + [[runtimes]] + src = "https://cdn.jsdelivr.net/pyodide/v0.20.0/full/pyodide.js" + name = "pyodide-0.20.0" + lang = "python" + +``` + +## Supplying extra information (or metadata) + Besides the above schema, a user can also supply any extra keys and values that are relevant as metadata information or perhaps are being used within the application. For example, a valid config could also be with the snippet below: