diff --git a/README.md b/README.md index 97510a2..c10714d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,13 @@ # pyscript-bootstrap-templates -templates and pyscript wrappers for various bootstrap properties + +This package provides tools to write a single page Dashboard apps with python that run entirely client-side in the Browser. +To do this, it uses [pyscript](https://pyscript.net/) and builds python wrapper classes for various [bootstrap](https://getbootstrap.com/) elements. + +![image-20230604191240295](img/demo.png) + +* See the examples here (`TODO`) + * (Code is in [examples](./examples/)) ## installation @@ -10,11 +17,76 @@ pip install git+https://the-cake-is-a-lie.net/gogs/jonas/pyscript-bootstrap-temp ## usage + +### create a project to create a new project, run ```bash -pyscript_bootstrap_app create +pyscript_bootstrap_app create <project_name> <title> --packages PACKAGES [PACKAGES ...] ``` -this will create a new folder containing a PWA app skeleton to start with. -The main entry point should be in main.py \ No newline at end of file +* this will create a new folder containing a PWA app skeleton to start with. +The main entry point should be in main.py + +* this will also create all necessary files such that this app can operate as an standalone PWA application. + +* the `packages` parameter is optional, you can specify on which PyPi packages your code depends + * **NOTE**: since pyscript's python implementation depends on WASM and it's limited in what it can do, not pure python packages may not work. Here is a list of supported packages: https://pyodide.org/en/stable/usage/packages-in-pyodide.html + +### update a project +Since it's a pwa, browsers will cache all content of the app for offline usage. To bump the version of the PWA and trigger a redownload after the project has changed, +simply run + +```bash +pyscript_bootstrap_app update <project_name> <title> +``` + +### serving a project for development + +you can use python's builtin webserver to serve the files locally for testing. Just run + +```bash +python -m http.server 1111 +``` + +inside your project folder and navigate to http://localhost:1111 in your browser + +### advanced usage +There are a few more options you can pass to `pyscript_bootstrap_app` (e.g. the pyscript version that is used). Here is the full list: + +```bash +usage: pyscript_bootstrap_app [-h] [--packages PACKAGES [PACKAGES ...]] [--paths PATHS [PATHS ...]] [--pyscript-css-url PYSCRIPT_CSS_URL] [--pyscript-js-url PYSCRIPT_JS_URL] + [--pyscript-py-url PYSCRIPT_PY_URL] [--bootstrap-css-url BOOTSTRAP_CSS_URL] [--bootstrap-js-url BOOTSTRAP_JS_URL] + [--pyscript-bootstrap-templates-wheel-url PYSCRIPT_BOOTSTRAP_TEMPLATES_WHEEL_URL] [--pwa-bg-color PWA_BG_COLOR] [--pwa-theme-color PWA_THEME_COLOR] + {create,update} root_folder title + +create a new pyscript project + +positional arguments: + {create,update} + root_folder the root folder of the new project + title the title of the new project + +options: + -h, --help show this help message and exit + --packages PACKAGES [PACKAGES ...] + the packages to include in the new project + --paths PATHS [PATHS ...] + additional local python files to include in the new project + --pyscript-css-url PYSCRIPT_CSS_URL + the url of the pyscript css file + --pyscript-js-url PYSCRIPT_JS_URL + the url of the pyscript js file + --pyscript-py-url PYSCRIPT_PY_URL + the url of the pyscript py file + --bootstrap-css-url BOOTSTRAP_CSS_URL + the url of the bootstrap css file + --bootstrap-js-url BOOTSTRAP_JS_URL + the url of the bootstrap js file + --pyscript-bootstrap-templates-wheel-url PYSCRIPT_BOOTSTRAP_TEMPLATES_WHEEL_URL + the url of the pyscript bootstrap templates wheel file + --pwa-bg-color PWA_BG_COLOR + background color for pwa configuration + --pwa-theme-color PWA_THEME_COLOR + theme color for pwa configuration +``` diff --git a/img/demo.png b/img/demo.png new file mode 100644 index 0000000..9b4ccfc Binary files /dev/null and b/img/demo.png differ