Skip to content

Commit

Permalink
docs: improve doc
Browse files Browse the repository at this point in the history
  • Loading branch information
jourdain committed Sep 19, 2023
1 parent 8617dc1 commit 427f79f
Show file tree
Hide file tree
Showing 16 changed files with 275 additions and 76 deletions.
16 changes: 3 additions & 13 deletions docs/vitepress/.vitepress/config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ export default defineConfig({
{ text: 'Cheatsheet', link: '/guide/intro/cheatsheet' },
{ text: 'Course', link: '/guide/intro/course' },
// { text: 'Vue 2/3 client', link: '/guide/intro/vue23' },
{ text: 'Widgets', link: '/guide/intro/widgets' },
]
},
{
Expand Down Expand Up @@ -96,20 +97,9 @@ export default defineConfig({
text: 'Core functionalities',
items: [
{ text: 'Basics', link: '/examples/core/basics' },
{ text: 'File management', link: '/examples/core/files' },
{ text: 'Files', link: '/examples/core/files' },
{ text: 'Jupyter', link: '/examples/core/jupyter' },

// { text: 'CLI', link: 'https://github.com/Kitware/trame/blob/master/examples/00_howdoi/cli.py' },
// { text: 'File Upload', link: 'https://github.com/Kitware/trame/blob/master/examples/00_howdoi/upload.py' },
// { text: 'Router', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/10_router.py' },
// { text: 'Favicon', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/12_reserved_state.py' },
// { text: 'MouseTrap', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/16_mousetrap.py'},
// { text: 'Download text', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/22_download_server_content.py' },
// { text: 'Download binary', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/24_vtk_download_image.py' },
// { text: 'CSS', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/28_css.py' },
// { text: 'Class decorator', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/decorators/default_class_decorator.py' },
// { text: 'Panel comparison', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/panel' },
// { text: 'Docker', link: 'https://github.com/Kitware/trame/blob/master/examples/deploy/docker/SingleFile' },
// router, docker
]
},
{
Expand Down
8 changes: 4 additions & 4 deletions docs/vitepress/examples/core/basics.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,8 @@ The examples presented below are meant to be executed and explored so you can un
## State management

::: code-group

<<< @/../../examples/core_features/state.py
<<< @/../../examples/core_features/reserved_state.py

:::

## Events management
Expand All @@ -18,10 +16,8 @@ The examples presented below are meant to be executed and explored so you can un
## User Interface

::: code-group

<<< @/../../examples/core_features/dynamic_layout.py
<<< @/../../examples/core_features/multi_layout.py

:::

## Life Cycle
Expand All @@ -41,3 +37,7 @@ Once hot-reload is enabled by either using the `TRAME_HOT_RELOAD` environment va
But in the following example, you can use `watchdog` to execute the UI update on file change.

<<< @/../../examples/core_features/hot_reload.py

## Class for trame application

<<< @/../../examples/core_features/app.py
21 changes: 20 additions & 1 deletion docs/vitepress/examples/core/files.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,28 @@
## Download

::: code-group
<<< @/../../examples/core_features/download_txt.py
<<< @/../../examples/core_features/download_binary.py
:::

## Upload

<<< @/../../examples/core_features/upload.py

## Browse

<<< @/../../examples/core_features/sys_filebrowser.py
<<< @/../../examples/core_features/sys_filebrowser.py

## Local CSS file

::: code-group
<<< @/../../examples/core_features/custom_css.py
<<< @/../../examples/core_features/custom.css
:::

## Local images as URL

::: code-group
<<< @/../../examples/core_features/images_inline.py
<<< @/../../examples/core_features/images_http.py
:::
28 changes: 27 additions & 1 deletion docs/vitepress/examples/core/jupyter.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,29 @@
## Exposing a trame application into Jupyter
# Exposing a trame application into Jupyter

## Disable warning

```python
import os
os.environ["TRAME_DISABLE_V3_WARNING"] = "1"
```

## Define application

<<< @/../../examples/core_features/jupyter.py

## Use application within Jupyter

```python
cone = Cone()
await cone.ui.ready
cone.ui
```

![Trame in Jupyer](/assets/images/deployment/jupyter.png)

## Edit state in another cell

```python
cone.resolution = 4
```

27 changes: 27 additions & 0 deletions docs/vitepress/guide/intro/widgets.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
## Widgets compatibility and package name

| Widget name (trame.widget.{name}) | Package name | Supported version | Number of components |
| --- | --- | --- | --- |
| html | (built-in) | 2 & 3 | 80 |
| client | (built-in) | 2 & 3 | 5 |
| vuetify, vuetify2, vuetify3 | trame-vuetify | 2 & 3 | 146/156 |
| router | trame-router | 2 & 3 | 2 |
| vtk, paraview | trame-vtk | 2 & 3 | 15 |
| plotly | trame-plotly | 2 & 3 | 1 |
| xterm | trame-xterm | 2 & 3 | 1 |
| code | trame-code | 2 & 3 | 1 |
| iframe | trame-iframe | 2 & 3 | 2 |
| trame | trame-components | 2 & 3 | 11 |
| keycloak | trame-keycloak | 2 & 3 (wip) | 1 |
| quasar | trame-quasar | 3 | 123 |
| formkit | trame-formkit | 3 | 2 |
| leaflet | trame-leaflet | 2 | 22 |
| pvui | trame-pvui | 2 | . |
| grid | trame-grid-layout | 2 | 2 |
| tauri | trame-tauri | 2 | - |
| vega | trame-vega | 2 | 1 |
| simput | trame-simput | 2 | 2 |
| rca | trame-rca | 2 (wip for 3) | 7 |
| matplotlib | trame-matplotlib | 2 | 1 |
| markdown | trame-markdown | 2 | 1 |
| deckgl | trame-deckgl | 2 | 1 |
28 changes: 1 addition & 27 deletions docs/vitepress/guide/versions/trame_v2-3.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,30 +79,4 @@ os.environ["TRAME_DISABLE_V3_WARNING"] = "1"

Trame in itself won't have API change but it is possible that vue3 widget will have a different API like you can see between vuetify2 and vuetify3, but in general we'll try to maintain full API compatibility.

## Widgets compatibility and package name

| Widget name (trame.widget.{name}) | Package name | Supported version |
| --- | --- | --- |
| html | (built-in) | 2 & 3 |
| client | (built-in) | 2 & 3 |
| vuetify, vuetify2, vuetify3 | trame-vuetify | 2 & 3 |
| router | trame-router | 2 & 3 |
| vtk, paraview | trame-vtk | 2 & 3 |
| plotly | trame-plotly | 2 & 3 |
| xterm | trame-xterm | 2 & 3 |
| code | trame-code | 2 & 3 |
| iframe | trame-iframe | 2 & 3 |
| trame | trame-components | 2 & 3 |
| keycloak | trame-keycloak | 2 & 3 (wip) |
| formkit | trame-formkit | 3 |
| leaflet | trame-leaflet | 2 |
| video | trame-video | 2 |
| pvui | trame-pvui | 2 |
| grid | trame-grid-layout | 2 |
| tauri | trame-tauri | 2 |
| vega | trame-vega | 2 |
| simput | trame-simput | 2 |
| rca | trame-rca | 2 (wip for 3) |
| matplotlib | trame-matplotlib | 2 |
| markdown | trame-markdown | 2 |
| deckgl | trame-deckgl | 2 |
<!--@include: ../intro/widgets.md-->
53 changes: 53 additions & 0 deletions examples/core_features/app.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
from trame.app import get_server
from trame.decorators import TrameApp, change, controller, trigger, life_cycle
from trame.ui.html import DivLayout
from trame.widgets import html


@TrameApp()
class App:
def __init__(self, name=None):
self.server = get_server(name)
self.ui()

@property
def state(self):
return self.server.state

@property
def ctrl(self):
return self.server.controller

@trigger("exec")
def method_call(self, msg):
print("method_called", msg)

@controller.set("hello")
def method_on_ctrl(self, *args):
print("method_on_ctrl", args)

@change("resolution")
def one_slider(self, resolution, **kwargs):
print("Slider value 1", resolution)

@life_cycle.server_ready
def on_ready(self, *args, **kwargs):
print("on_ready")

def ui(self):
with DivLayout(self.server) as layout:
html.Input(
type="range",
min=3,
max=60,
step=1,
v_model_number=("resolution", 6),
)
html.Button("trigger", click="trigger('exec', ['trigger'])")
html.Button("method", click=(self.method_call, "['method']"))
html.Button("ctrl", click=self.ctrl.hello)


if __name__ == "__main__":
app = App()
app.server.start()
3 changes: 3 additions & 0 deletions examples/core_features/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
body {
background-color: red;
}
15 changes: 15 additions & 0 deletions examples/core_features/custom_css.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
from pathlib import Path

from trame.app import get_server
from trame.widgets import client
from trame.ui.html import DivLayout

CSS_FILE = Path(__file__).with_name("custom.css")

server = get_server()
with DivLayout(server):
client.Style(CSS_FILE.read_text())


if __name__ == "__main__":
server.start()
24 changes: 24 additions & 0 deletions examples/core_features/download_binary.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
from pathlib import Path
from trame.app import get_server
from trame.ui.html import DivLayout
from trame.widgets import html

BINARY_FILE = Path(__file__).parent.parent / "data/can.ex2"

server = get_server()
state, ctrl = server.state, server.controller


@ctrl.trigger("download_binary")
def download():
return server.protocol.addAttachment(BINARY_FILE.read_bytes())


with DivLayout(server):
html.Button(
"Download ",
click="utils.download('can.ex2', trigger('download_binary'), 'application/octet-stream')",
)

if __name__ == "__main__":
server.start()
28 changes: 28 additions & 0 deletions examples/core_features/download_txt.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
import time
from trame.app import get_server
from trame.ui.html import DivLayout
from trame.widgets import html

server = get_server()
state, ctrl = server.state, server.controller

state.other_txt_content = "Some content to download..."


@ctrl.trigger("download_content")
def generate_content():
return f"Hello on the server is {time.time()}"


with DivLayout(server):
html.Button(
"Download from method",
click="utils.download('method.txt', trigger('download_content'), 'text/plain')",
)
html.Button(
"Download from state",
click="utils.download('state.txt', other_txt_content, 'text/plain')",
)

if __name__ == "__main__":
server.start()
2 changes: 0 additions & 2 deletions examples/core_features/events.py
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,6 @@ def method_4(*args, **kwargs):
# UI setup
# -----------------------------------------------------------------------------

layout = DivLayout(server)

with DivLayout(server):
html.Div(
"State a={{ a }}", style="padding: 20px; margin: 20px; border: solid 1px #333;"
Expand Down
19 changes: 19 additions & 0 deletions examples/core_features/images_http.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
from pathlib import Path

from trame.app import get_server
from trame.widgets import html
from trame.ui.html import DivLayout


DIRECTORY = Path(__file__).parent.parent.parent / "docs/vitepress/assets/images/apps"

server = get_server()
server.enable_module({"serve": {"data": str(DIRECTORY.absolute())}})

with DivLayout(server):
for file in DIRECTORY.iterdir():
html.Img(src=f"/data/{file.name}", style="width: 200px;")


if __name__ == "__main__":
server.start()
26 changes: 26 additions & 0 deletions examples/core_features/images_inline.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
from pathlib import Path

from trame.app import get_server
from trame.assets.local import LocalFileManager
from trame.widgets import html
from trame.ui.html import DivLayout


KEYS = []
DIRECTORY = Path(__file__).parent.parent.parent / "docs/vitepress/assets/images/apps"
ASSETS = LocalFileManager(DIRECTORY)

for image in DIRECTORY.iterdir():
key = image.stem.replace("-", "_")
ASSETS.url(key, image.name)
KEYS.append(key)


server = get_server()
with DivLayout(server):
for key in KEYS:
html.Img(src=ASSETS[key], style="width: 200px;")


if __name__ == "__main__":
server.start()
Loading

0 comments on commit 427f79f

Please sign in to comment.