New user feedback

doc/conf.py

@@ -258,14 +258,16 @@ def _get_pyodide_version():
 
 def update_versions(app, docname, source):
     from panel.models.tabulator import TABULATOR_VERSION
+    from panel.models.vizzu import VIZZU_VERSION
 
     # Inspired by: https://stackoverflow.com/questions/8821511
     version_replace = {
-       "{{PANEL_VERSION}}" : PY_VERSION,
-       "{{BOKEH_VERSION}}" : BOKEH_VERSION,
-       "{{PYSCRIPT_VERSION}}" : PYSCRIPT_VERSION,
-       "{{PYODIDE_VERSION}}" : _get_pyodide_version(),
-       "{{TABULATOR_VERSION}}" : TABULATOR_VERSION,
+        "{{PANEL_VERSION}}" : PY_VERSION,
+        "{{BOKEH_VERSION}}" : BOKEH_VERSION,
+        "{{PYSCRIPT_VERSION}}" : PYSCRIPT_VERSION,
+        "{{PYODIDE_VERSION}}" : _get_pyodide_version(),
+        "{{TABULATOR_VERSION}}" : TABULATOR_VERSION,
+        "{{VIZZU_VERSION}}" : VIZZU_VERSION,
     }
 
     for old, new in version_replace.items():

doc/explanation/api/examples/outliers_declarative.md

@@ -82,3 +82,40 @@ pn.Column(obj.param, obj.view)
 ```
 
 To support various domains, you can create hierarchies of classes encapsulating parameters and functionality across different object families. Parameters and code can inherit across classes as needed, without depending on any specific GUI library. This approach facilitates the maintenance of large codebases, all displayable and editable with Panel, adaptable over time. For a more complex illustration, refer to the [Attractors Panel app](https://examples.holoviz.org/gallery/attractors/attractors_panel.html) ([source](https://github.com/holoviz-topics/examples/tree/main/attractors)), and explore the Panel codebase itself for extensive usage of Param throughout the codebase.
+
+## Serving the Notebook
+
+Lets finalize our app by organizing our components in a nicely styled template (`MaterialTemplate`) and mark it `.servable()` to add it to our served app:
+
+```python
+pn.template.MaterialTemplate(
+    site="Panel",
+    title="Getting Started App",
+    sidebar=[obj.param],
+    main=[obj.view],
+).servable(); # The ; is needed in the notebook to not display the template. Its not needed in a script
+```
+
+Save the notebook with the name `app.ipynb`.
+
+Finally, we'll serve the app by running the command below in a terminal:
+
+```bash
+panel serve app.ipynb --dev
+```
+
+Now, open the app in your browser at [http://localhost:5006/app](http://localhost:5006/app).
+
+It should look like this:
+
+![Getting Started App](../../../_static/images/getting_started_app.png)
+
+:::{tip}
+
+If you prefer developing in a Python Script using an editor, you can copy the code into a file `app.py` and serve it.
+
+```bash
+panel serve app.py --autoreload
+```
+
+:::

doc/getting_started/build_app.md

@@ -14,7 +14,7 @@ If you're eager to roll up your sleeves and build this app alongside us, we reco
 Initially, the code block outputs on this website offer limited interactivity, indicated by the <font color="darkgoldenrod">golden</font> border to the left of the output below. By clicking the play button (<svg class="pyodide-run-icon" style="width:32px;height:25px" viewBox="0 0 24 24"> <path stroke="none" fill="#28a745" d="M8,5.14V19.14L19,12.14L8,5.14Z"></path> </svg>), you can activate full interactivity, marked by a <font color="green">green</font> left-border.
 :::
 
-## Fetching the Data
+## Configuring the Application
 
 First, let's import the necessary dependencies and define some variables:
 
@@ -37,6 +37,8 @@ Next, we'll import the Panel JavaScript dependencies using `pn.extension(...)`.
 pn.extension(design="material", sizing_mode="stretch_width")
 ```
 
+## Fetching the Data
+
 Now, let's load the [UCI ML dataset](http://archive.ics.uci.edu/dataset/357/occupancy+detection) that measured the environment in a meeting room. We'll speed up our application by caching (`@pn.cache`) the data across users:
 
 ```{pyodide}
@@ -121,7 +123,7 @@ pn.template.MaterialTemplate(
 
 Save the notebook with the name `app.ipynb`.
 
-Finally, we'll serve the app with:
+Finally, we'll serve the app by running the command below in a terminal:
 
 ```bash
 panel serve app.ipynb --dev
@@ -133,15 +135,71 @@ It should look like this:
 
 ![Getting Started App](../_static/images/getting_started_app.png)
 
-:::{tip}
+::::{tip}
+
+If you prefer developing in a Python Script using an editor, you can copy the *code* into a file `app.py` and serve it.
+
+:::{dropdown} code
+
+```python
+import hvplot.pandas
+import numpy as np
+import pandas as pd
+import panel as pn
+
+PRIMARY_COLOR = "#0072B5"
+SECONDARY_COLOR = "#B54300"
+CSV_FILE = (
+    "https://raw.githubusercontent.com/holoviz/panel/main/examples/assets/occupancy.csv"
+)
+
+pn.extension(design="material", sizing_mode="stretch_width")
 
-If you prefer developing in a Python Script using an editor, you can copy the code into a file `app.py` and serve it.
+@pn.cache
+def get_data():
+  return pd.read_csv(CSV_FILE, parse_dates=["date"], index_col="date")
+
+data = get_data()
+
+def transform_data(variable, window, sigma):
+    """Calculates the rolling average and identifies outliers"""
+    avg = data[variable].rolling(window=window).mean()
+    residual = data[variable] - avg
+    std = residual.rolling(window=window).std()
+    outliers = np.abs(residual) > std * sigma
+    return avg, avg[outliers]
+
+
+def get_plot(variable="Temperature", window=30, sigma=10):
+    """Plots the rolling average and the outliers"""
+    avg, highlight = transform_data(variable, window, sigma)
+    return avg.hvplot(
+        height=300, legend=False, color=PRIMARY_COLOR
+    ) * highlight.hvplot.scatter(color=SECONDARY_COLOR, padding=0.1, legend=False)
+
+variable_widget = pn.widgets.Select(name="variable", value="Temperature", options=list(data.columns))
+window_widget = pn.widgets.IntSlider(name="window", value=30, start=1, end=60)
+sigma_widget = pn.widgets.IntSlider(name="sigma", value=10, start=0, end=20)
+
+bound_plot = pn.bind(
+    get_plot, variable=variable_widget, window=window_widget, sigma=sigma_widget
+)
+
+pn.template.MaterialTemplate(
+    site="Panel",
+    title="Getting Started App",
+    sidebar=[variable_widget, window_widget, sigma_widget],
+    main=[bound_plot],
+).servable(); # The ; is needed in the notebook to not display the template. Its not needed in a script
+```
+
+:::
 
 ```bash
 panel serve app.py --dev
 ```
 
-:::
+::::
 
 ## What's Next?
 

doc/how_to/editor/vscode_configure.md

@@ -1,85 +1,49 @@
 # Configure VS Code
 
-This guide addresses how to configure VS Code for an efficient Panel development workflow.
+This guide explains how to configure VS Code for an efficient Panel development workflow.
 
-We assume you have
+We assume you have:
 
-- a basic understanding of [working with Python in VS Code](https://code.visualstudio.com/docs/python/python-tutorial).
-- installed the VS Code [Python extension](https://github.com/Microsoft/vscode-python)
+- [x] The **latest version of VS Code installed**.
+- [x] A basic understanding of [working with Python in VS Code](https://code.visualstudio.com/docs/python/python-tutorial).
+- [x] Installed the **latest versions** of the VS Code extensions:
+  - [Python](https://github.com/Microsoft/vscode-python)
+  - [Jupyter](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter) including [Jupyter Notebook Renderers](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter-renderers)
 
 ---
 
-## Debugging
-
-To learn how to use the *integrated debugger* in general check out [the official guide](https://code.visualstudio.com/docs/editor/debugging).
-
-To configure the integrated debugger for Panel, you will need to add a debugging configuration like the below.
-
-```bash
-{
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "name": "panel serve",
-            "type": "python",
-            "request": "launch",
-            "program": "-m",
-            "args": [
-                "panel",
-                "serve",
-                "${relativeFile}",
-                "--show"
-            ],
-            "console": "integratedTerminal",
-            "justMyCode": true
-        },
-    ]
-}
-```
+## Installation
 
-In use it looks like
+:::info
 
-![Integrated Debugging of a Panel app in VS Code](../../_static/images/vscode-integrated-debugging.png)
+For `panel` to work with the [VS Code Jupyter Extension](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter) and [Jupyter Notebook Renderers](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter-renderers)
+you need to have [`jupyter_bokeh`](https://github.com/bokeh/jupyter_bokeh) and [`ipykernel`](https://github.com/ipython/ipykernel) installed in your virtual environment.
 
-## Extensions
+We strongly recommend you to install into a **new virtual environment** before starting to use Panel with in the Interactive environment. Installing `jupyter_bokeh` and `ipykernel` into an old environment can lead to problems that are hard to reproduce, understand and solve.
 
-The following extensions will help speed up your Panel workflow
+:::
 
-- [Live Server](https://github.com/ritwickdey/vscode-live-server-plus-plus): Enables you to easily view `.html` files created using `.save()` or `panel convert`.
+Install the requirements
 
-## General Settings
+:::::{tab-set}
 
-We recommend adding the below to your `settings.json` file on Windows
+::::{tab-item} pip
 
 ```bash
-"explorer.copyRelativePathSeparator": "/" # Relevant on Windows only
+pip install panel watchfiles jupyter_bokeh ipykernel
 ```
 
-## Keyboard Shortcuts
+::::
 
-To speed up your workflow we recommend configuring a keyboard short cut to `panel serve` your app.
+::::{tab-item} conda
 
-```bash
-[
-    {
-        "key": "ctrl+shift+space",
-        "command": "workbench.action.terminal.sendSequence",
-        "args": { "text": "panel serve ${relativeFile} --autoreload --show\u000D" }
-    }
-]
-```
-
-On Windows you will need to add quotes around `${relativeFile}`, i.e. replace it with `'${relativeFile}'`.
+conda install -c conda-forge panel watchfiles jupyter_bokeh ipykernel
 
-When you press `CTRL+SHIFT+SPACE` you will `panel serve` your file in the terminal, if you have an open terminal.
-
-## Notebook and Interactive Environment
+::::
 
-Ensure you install `jupyter_bokeh` with `pip install jupyter_bokeh` or `conda install -c bokeh jupyter_bokeh` and then enable the extension with `pn.extension()`.
+:::::
 
-You can see a notebook in action below.
-
-![Panel in VS Code Notebook Environment](../../_static/images/vscode-notebook.png)
+You should now be able to `panel serve` your python file or notebook as usual.
 
 ## Simple Browser
 
@@ -128,6 +92,96 @@ and keybinding to `keybindings.json`
 ]
 ```
 
+## Notebook and Interactive Environment
+
+If you have followed the [installation instructions above](#installation) and added `pn.extension()` after your python imports you should be able to use the Jupyter Interactive environment as shown below.
+
+![Panel in VS Code Notebook Environment](../../_static/images/vscode-notebook.png)
+
+### Trouble Shooting
+
+The support for Jupyter and Panel widgets in the interactive environment is fragile and you might experience issues.
+
+Below is some advice for solving the issues. If that does not work for you, try
+
+- closing the interactive window
+- upgrading VS Code to the latest version
+- upgrading the Python and Jupyter VS Code extensions to the latest versions
+- creating a new virtual environment, install as [described above](#installation)
+- restarting VS code.
+
+#### No output
+
+If your first output does not show, try executing the command in a new cell. Sometimes VS Code need a little time to install some javascript packages behind the scenes.
+
+![VS Code No Output](../../_static/images/vscode-no-output-try-again.png)
+
+## Debugging
+
+To learn how to use the *integrated debugger* in general, check out [the official guide](https://code.visualstudio.com/docs/editor/debugging).
+
+To enable debugging applications with `panel serve`, you can add a `"panel serve"` debugging configuration like the one below to your VS Code debugging configuration file.
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "panel serve",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "-m",
+            "args": [
+                "panel",
+                "serve",
+                "${relativeFile}",
+                "--index",
+                "${fileBasenameNoExtension}",
+                "--show"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": true
+        }
+    ]
+}
+```
+
+When used, it looks like this:
+
+![Integrated Debugging of a Panel app in VS Code](../../_static/images/vscode-integrated-debugging.png)
+
+## Extensions
+
+The following optional extensions can help speed up your Panel workflow
+
+- [Live Server](https://github.com/ritwickdey/vscode-live-server-plus-plus): Enables you to easily view `.html` files created using `.save()` or `panel convert`.
+
+## General Settings
+
+We recommend adding the below to your `settings.json` file on Windows
+
+```bash
+"explorer.copyRelativePathSeparator": "/" # Relevant on Windows only
+```
+
+## Keyboard Shortcuts
+
+To speed up your workflow we recommend configuring a keyboard short cut to `panel serve` your app.
+
+```bash
+[
+    {
+        "key": "ctrl+shift+space",
+        "command": "workbench.action.terminal.sendSequence",
+        "args": { "text": "panel serve ${relativeFile} --autoreload --show\u000D" }
+    }
+]
+```
+
+On Windows you will need to add quotes around `${relativeFile}`, i.e. replace it with `'${relativeFile}'`.
+
+When you press `CTRL+SHIFT+SPACE` you will `panel serve` your file in the terminal, if you have an open terminal.
+
 ## Snippets
 
 To speed up your workflow you can configure [*user defined snippets*](https://code.visualstudio.com/docs/editor/userdefinedsnippets) like these [example Panel snippets](../../_static/json/vscode-snippets-python.json). When you start typing `import panel` you will get the option to select between the snippets as shown below.