diff --git a/doc/explanation/api/examples/outliers_declarative.md b/doc/explanation/api/examples/outliers_declarative.md index de58693c2e..c83ccbd03a 100644 --- a/doc/explanation/api/examples/outliers_declarative.md +++ b/doc/explanation/api/examples/outliers_declarative.md @@ -2,11 +2,15 @@ This section introduces a more advanced and powerful method of creating Panel apps using a declarative, class-based approach. It builds upon the simple app demonstrated in the [Getting Started > Build an app](../../../getting_started/build_app.md) tutorial, which utilized the reactive, function-based API. +![Getting Started App](../../../_static/images/getting_started_app.png) + While the reactive API approach is flexible, it intertwines domain-specific code with widget display code. This works well for small projects or those heavily focused on visualization. However, for larger, long-term projects used across various contexts like batch runs, command-line usage, notebooks, and deployed dashboards, it becomes crucial to separate domain logic from display technologies. For such scenarios, Panel supports the use of objects declared with the separate [Param](http://param.holoviz.org) library. Param provides a GUI-independent way to capture and declare object parameters and dependencies, irrespective of any specific application or dashboard technology. This allows for modularization, making it easier to manage and reuse code across different environments. -In this approach, the app's logic is encapsulated within a class, separating concerns and promoting code organization. Let's walk through the steps: +In this approach, the app's logic is encapsulated within a class, separating concerns and promoting code organization. + +Let's begin by reusing most of the code from the [Getting Started > Build an app](../../../getting_started/build_app.md) tutorial: ```{pyodide} import hvplot.pandas diff --git a/doc/getting_started/build_app.md b/doc/getting_started/build_app.md index 26f5bce132..ef798e3845 100644 --- a/doc/getting_started/build_app.md +++ b/doc/getting_started/build_app.md @@ -1,8 +1,8 @@ -# {octicon}`tools;2em;sd-mr-1` Build an App +# {octicon}`mortar-board;2em;sd-mr-1` Build an App By now, you should have [set up your environment and installed Panel](installation.md), so you're all set to dive in! -In this section, we'll walk through creating a basic interactive application using [NumPy](https://numpy.org/), [Pandas](https://pandas.pydata.org/), and [hvplot](https://hvplot.holoviz.org/). If you haven't installed `hvPlot` yet, you can do so with `pip install hvplot` or `conda install -c conda-forge hvplot`. +In this section, we'll walk through creating a basic interactive application using [NumPy](https://numpy.org/), [Pandas](https://pandas.pydata.org/), and [hvPlot](https://hvplot.holoviz.org/). If you haven't installed `hvPlot` yet, you can do so with `pip install hvplot` or `conda install -c conda-forge hvplot`. Let's envision what our app will look like: @@ -37,7 +37,7 @@ Next, we'll import the Panel JavaScript dependencies using `pn.extension(...)`. pn.extension(design="material", sizing_mode="stretch_width") ``` -Now, let's load the [UCI ML dataset](http://archive.ics.uci.edu/ml/datasets/Occupancy+Detection+) that measured the environment in a meeting room: +Now, let's load the [UCI ML dataset](http://archive.ics.uci.edu/ml/datasets/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} @pn.cache @@ -49,11 +49,9 @@ data = get_data() data.tail() ``` -We'll speed up our application by caching (`@pn.cache`) the data across users. - ## Visualizing a Subset of the Data -Before diving into Panel, let's create a function that smooths one of our time series and identifies outliers. Then, we'll plot the result using hvplot: +Before diving into Panel, let's create a function that smooths one of our time series and identifies outliers. Then, we'll plot the result using hvPlot: ```{pyodide} def transform_data(variable, window, sigma): @@ -112,7 +110,7 @@ As long as you have a live Python process running, dragging these widgets will t We'll organize our components in a nicely styled template (`MaterialTemplate`) and mark it `.servable()` to add it to our served app: -```{pyodide} +```python pn.template.MaterialTemplate( site="Panel", title="Getting Started App", @@ -129,13 +127,13 @@ Finally, we'll serve the app with: panel serve app.ipynb --autoreload ``` -Now, open the app in your browser at `http://localhost:5006/app`. +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) -:::{note} +:::{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. @@ -143,6 +141,8 @@ If you prefer developing in a Python Script using an editor, you can copy the co panel serve app.py --autoreload ``` +::: + ## What's Next? Now that you've experienced how easy it is to build a simple application in Panel, it's time to delve into some of the [core concepts](core_concepts.md) behind Panel. diff --git a/doc/getting_started/core_concepts.md b/doc/getting_started/core_concepts.md index 27a844b8d8..720387a039 100644 --- a/doc/getting_started/core_concepts.md +++ b/doc/getting_started/core_concepts.md @@ -1,4 +1,4 @@ -# Core Concepts +# {octicon}`telescope;2em;sd-mr-1` Core Concepts In the previous section, we delved into [building a simple app](build_app.md). A Panel app like this makes exploration of various visualizations very easy, supporting types such as Matplotlib, Bokeh, Plotly, Altair, DataFrame, and various text and image types. @@ -15,10 +15,10 @@ As you gear up to develop your Panel application, you'll encounter a couple of i :::{dropdown} Interested in a class-based approach instead? :margin: 4 :color: muted - Explore the same ['outlier' app built using a class-based declarative API](../explanation/api/examples/outliers_declarative.md). Study the [Explanation > APIs](../explanation/apis/index.md) section for a detailed discussion on each of the API options. + Explore the same ['outlier' app built using a class-based declarative API](../explanation/api/examples/outliers_declarative.md). Study the [Explanation > APIs](../explanation/api/index.md) section for a detailed discussion on each of the API options. ::: -2. **Development Environment:** Will you develop in a [notebook](https://jupyter.org/) or in an editor environment? +2. **Development Environment:** Will you develop in a notebook or in an editor environment? - If you're unsure, starting in a notebook is recommended as you familiarize yourself with Panel. However, you can switch between them at any time. ### Notebook @@ -54,17 +54,19 @@ Upon running that command, Panel launches a server that serves your app, opens a -```{note} -We recommend installing `watchfiles` to get the best user experience when using `--autoreload`. +```{tip} +We recommend installing [`watchfiles`](https://watchfiles.helpmanual.io) to get the best user experience when using `--autoreload`. ``` -> Explore [How-to > Prepare to Develop](../how_to/prepare_to_develop.md) for more guidance on each development environment option. +```{tip} +Explore [How-to > Prepare to Develop](../how_to/prepare_to_develop.md) for more guidance on each development environment option. +``` ## Control Flow Panel operates on a powerful framework called [Param](https://param.holoviz.org/), which governs how information flows within your app. When a change occurs, such as the value of a slider or a manual update in your code, events are triggered for your app to respond to. Panel provides various methods for setting up this interactivity. Understanding the basics of Param is crucial to mastering Panel. However, it's not necessary to get started as a new, basic user. -So, what exactly is Param? It's a framework that enables Python classes to have attributes with defaults, type/value validation, and callbacks when values change. You can liken it to other frameworks like Python dataclasses, pydantic, and traitlets. +So, what exactly is Param? It's a framework that enables Python classes to have attributes with defaults, type/value validation, and callbacks when values change. You can liken it to other frameworks like Python dataclasses, [Pydantic](https://docs.pydantic.dev/latest/), and [Traitlets](https://traitlets.readthedocs.io). Reactivity is a key concept in both Param and Panel. This means changes in one part of your app can automatically update other parts. Think of it like Excel, where altering one cell can prompt updates in cells that reference it. Param objects operate similarly. @@ -74,7 +76,7 @@ In Panel, understanding the distinction between a Parameter's value and the Para text = pn.widgets.TextInput() text.value # 👈 The current value of the widget -text.param.value # 👈 A reference to the "value" Parameter, used in Panel to *bind* to the "value" +text.param.value # 👈 A reference to the "value" Parameter, used in Panel to bind to the "value" ``` We'll delve deeper into this later. For now, remember that parameter objects (whether associated with widgets or not) enable you to pass around a reference to a value that automatically updates if the original value changes. diff --git a/doc/getting_started/index.md b/doc/getting_started/index.md index dced8ca979..70a0446ba8 100644 --- a/doc/getting_started/index.md +++ b/doc/getting_started/index.md @@ -9,7 +9,7 @@ The getting started guides are for those who would like to **quickly try out Pan ::::{grid} 1 2 2 3 :gutter: 1 1 1 2 -:::{grid-item-card} {octicon}`plug;2.5em;sd-mr-1` Installation +:::{grid-item-card} {octicon}`desktop-download;2.5em;sd-mr-1` Installation :link: installation :link-type: doc diff --git a/doc/getting_started/installation.md b/doc/getting_started/installation.md index c6fd62ff1e..f180aa9c49 100644 --- a/doc/getting_started/installation.md +++ b/doc/getting_started/installation.md @@ -62,11 +62,11 @@ conda install panel watchfiles ::::: ```{tip} -We recommend also installing `watchfiles` while developing. This will provide a significantly better experience when using Panel's `--autoreload` feature. It's not needed for production. +We recommend also installing [`watchfiles`](https://watchfiles.helpmanual.io) while developing. This will provide a significantly better experience when using Panel's `--autoreload` feature. It's not needed for production. ``` :::{important} -Make sure Panel is installed in the same environment as JupyterLab/Jupyter Notebook (`conda install panel` or `pip install panel`) to ensure all features work correctly. +Make sure Panel is installed in the same environment as JupyterLab/Jupyter Notebook (`pip install panel` or `conda install panel`) to ensure all features work correctly. ::: :::{seealso} diff --git a/doc/tutorials/basic/develop_notebook.md b/doc/tutorials/basic/develop_notebook.md index 11979d5caa..84d6433eca 100644 --- a/doc/tutorials/basic/develop_notebook.md +++ b/doc/tutorials/basic/develop_notebook.md @@ -29,7 +29,7 @@ pn.panel("Hello World").servable() ``` ```python -pn.panel("Hello Again").servable() +pn.panel("Hello Again") ``` Run the cells and save the notebook as `app.ipynb`. diff --git a/doc/tutorials/basic/index.md b/doc/tutorials/basic/index.md index 456e5075f3..a02231b786 100644 --- a/doc/tutorials/basic/index.md +++ b/doc/tutorials/basic/index.md @@ -16,7 +16,7 @@ Please execute the following command to install the dependencies required by the :sync: pip ```bash -pip install altair hvplot matplotlib numpy pandas panel plotly scipy +pip install altair hvplot matplotlib numpy pandas panel plotly scipy watchfiles ``` ::: @@ -25,7 +25,7 @@ pip install altair hvplot matplotlib numpy pandas panel plotly scipy :sync: conda ```bash -conda install -y -c conda-forge altair hvplot matplotlib numpy pandas panel plotly scipy +conda install -y -c conda-forge altair hvplot matplotlib numpy pandas panel plotly scipy watchfiles ``` ::: @@ -33,7 +33,7 @@ conda install -y -c conda-forge altair hvplot matplotlib numpy pandas panel plot :::: :::{important} -Is Panel installed together with JupyterLab/Jupyter Notebook in your working environment? If not, you need to make sure that `panel` is also installed in the same environment as JupyterLab/Jupyter Notebook (`conda install -c conda-forge panel` or `pip install panel`). +Is Panel installed together with JupyterLab/Jupyter Notebook in your working environment? If not, you need to make sure that `panel` is also installed in the same environment as JupyterLab/Jupyter Notebook (`pip install panel` or `conda install panel`). ::: ## Let's Get Started @@ -94,16 +94,16 @@ align widgets pn_bind state +caching indicators_activity progressive_layouts -caching templates design style build_dashboard deploy -build_monitoring_dashboard build_report +build_monitoring_dashboard build_animation build_todo build_image_classifier