From 7770af603b8a697f7a5a28a2491d5621febf2091 Mon Sep 17 00:00:00 2001 From: Thibault Pelletier Date: Wed, 10 Jun 2026 10:05:59 +0200 Subject: [PATCH] docs: update jupyter doc - Update Jupyter doc with display_cell trame-client API --- docs/vitepress/guide/jupyter/advanced.md | 4 +- docs/vitepress/guide/jupyter/intro.md | 55 +++++++++++++++++++-- docs/vitepress/guide/jupyter/sample-code.md | 12 ++--- 3 files changed, 58 insertions(+), 13 deletions(-) diff --git a/docs/vitepress/guide/jupyter/advanced.md b/docs/vitepress/guide/jupyter/advanced.md index 4d37a765..b2763cd0 100644 --- a/docs/vitepress/guide/jupyter/advanced.md +++ b/docs/vitepress/guide/jupyter/advanced.md @@ -12,9 +12,8 @@ Let's review the various available options from module import App app = App() -await app.ui.ready app.ui.iframe_builder = "..." # <= force an iframe builder -app.ui +await app.display_cell() ``` | iframe_builder | URL | Default if | @@ -24,6 +23,7 @@ app.ui | jupyter-extension | ENV(TRAME_JUPYTER_WWW)/servers/{server.name}/ | Extension loaded and available | | jupyter-hub | ENV(JUPYTERHUB_SERVICE_PREFIX)proxy/{server.port}/ | If JUPYTERHUB_SERVICE_PREFIX exist | | jupyter-hub-host | ENV(JUPYTERHUB_SERVICE_PREFIX)proxy/{host}:{server.port}/ | Never a default | +| google-colab | google.colab.kernel.proxyPort({server.port}) | If COLAB_RELEASE_TAG or COLAB_BACKEND_VERSION exist | The selection can also be done via the __TRAME_IFRAME_BUILDER__ environment variable. diff --git a/docs/vitepress/guide/jupyter/intro.md b/docs/vitepress/guide/jupyter/intro.md index a0949b01..cb329f4a 100644 --- a/docs/vitepress/guide/jupyter/intro.md +++ b/docs/vitepress/guide/jupyter/intro.md @@ -1,7 +1,11 @@ # Trame and Jupyter Lab -A trame application, while working in standalone fashion, can also be imported inside Jupyter and displayed within a notebook. -To make that possible, the user will need to be able to import and instantiate such application in a Jupyter context. Then, the user will need to have access to the layout (ui) of that application so it can be displayed in the notebook flow. +A trame application, while working in standalone fashion, can also be imported inside Jupyter and displayed within a +notebook. + +To make that possible, the user will need to be able to import and instantiate such application in a Jupyter context. +Then, the user will need to have access to the layout (ui) of that application so it can be displayed in the notebook +flow. ## Simple example @@ -17,7 +21,6 @@ source .venv/bin/activate # => Linux / Mac # Install dependencies pip install trame trame-vtk trame-vuetify # adding vuetify + vtk.js for demo app -pip install setuptools # used in trame-vuetify but not always available nowaday pip install jupyterlab ``` @@ -37,11 +40,55 @@ from trame.app.demo import Cone app = Cone() # Put the UI into the resulting cell -app +await app.display_cell(height="600px") +``` + +```{note} +Alternatively, the application instance can be returned and used directly to display the cell in JupyterLab. +However this syntax will not work when used in google-colab's context where an explicit call to `display_cell` is +expected. +``` + +```python +# Alternative syntax to instantiate and display the app in JupyterLab cell +Cone() + +# The previous call is equivalent to instantiating the application, followed by a direct `repr` call +app = Cone() +app # This line will trigger the display of the app in the cell + +# However, for cross-compatibility with google-colab it's preferable to use the display_cell method +app = Cone() +await app.display_cell() ``` + This should look like ![Cone in Jupyter](/assets/images/jupyter/jupyter-cone.png) If you want [more examples using the same code, you can look at that binder example repository](https://github.com/Kitware/trame-binder). + +## google-colab + +Starting with trame-client v3.13.1 trame is compatible with google-colab's Jupyter environment. + +To run trame in google-colab, start by installing trame's dependencies. + +```jupyter +%%capture --no-stderr + +!pip install -q --upgrade trame trame-vtk trame-vuetify +``` + +The application can then be displayed using the `display_cell` method. + +```python +from trame.app.demo import Cone + +# Create new application instance +app = Cone() + +# Put the UI into the resulting cell +await app.display_cell(height="600px") +``` diff --git a/docs/vitepress/guide/jupyter/sample-code.md b/docs/vitepress/guide/jupyter/sample-code.md index 70cd95d5..6170edc2 100644 --- a/docs/vitepress/guide/jupyter/sample-code.md +++ b/docs/vitepress/guide/jupyter/sample-code.md @@ -14,16 +14,15 @@ When a trame application is laid out like above, you can just run the following from module import App app = App() -await app.ui.ready -app.ui +await app.display_cell(height="600px") ``` And in case you want to have a second instance independent of the first one, you can do ```python app2 = App('v2') -await app2.ui.ready -app2.ui + +await app2.display_cell(height="600px") ``` ## Changing application state @@ -69,8 +68,7 @@ with DivLayout(server, 'a', height=30) as ui_a: style="width: 100%;", ) -await ui_a.ready -ui_a +await ui_a.display_cell() ``` Then you can create more ui on the same server @@ -83,7 +81,7 @@ with DivLayout(server, 'b', height=30) as ui_b: ) html.Span("{{ slider_a }} / 2 = {{ result }}", style="margin-left: 2rem") -ui_b +await ui_b.display_cell() ``` ![Multi-UI in Jupyter](/assets/images/jupyter/multi-ui.png)