Add tutorial section for documentation (#6213)

holoviz · Feb 25, 2024 · 6ee12f6 · 6ee12f6
1 parent a88bd43
commit 6ee12f6
Show file tree

Hide file tree

Showing 133 changed files with 7,543 additions and 1,556 deletions.
diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
@@ -77,3 +77,7 @@ button.copybtn:hover {
 .o-tooltip--left:after {
   background: none;
 }
+
+video {
+  max-width: 100%;
+}
diff --git a/doc/_static/images/align-cards-solution.png b/doc/_static/images/align-cards-solution.png
diff --git a/doc/_static/images/awesome-panel.png b/doc/_static/images/awesome-panel.png
diff --git a/doc/_static/images/develop_editor_breakpoint.png b/doc/_static/images/develop_editor_breakpoint.png
diff --git a/doc/_static/images/develop_editor_click_me.png b/doc/_static/images/develop_editor_click_me.png
diff --git a/doc/_static/images/develop_editor_hover.png b/doc/_static/images/develop_editor_hover.png
diff --git a/doc/_static/images/develop_editor_layout0.png b/doc/_static/images/develop_editor_layout0.png
diff --git a/doc/_static/images/develop_editor_layout1.png b/doc/_static/images/develop_editor_layout1.png
diff --git a/doc/_static/images/develop_editor_panel_serve_after.png b/doc/_static/images/develop_editor_panel_serve_after.png
diff --git a/doc/_static/images/develop_editor_panel_serve_before.png b/doc/_static/images/develop_editor_panel_serve_before.png
diff --git a/doc/_static/images/develop_editor_param.png b/doc/_static/images/develop_editor_param.png
diff --git a/doc/_static/images/develop_editor_reference_guide.png b/doc/_static/images/develop_editor_reference_guide.png
diff --git a/doc/_static/images/develop_editor_serve_app.png b/doc/_static/images/develop_editor_serve_app.png
diff --git a/doc/_static/images/develop_notebook_panel_serve_after.png b/doc/_static/images/develop_notebook_panel_serve_after.png
diff --git a/doc/_static/images/develop_notebook_panel_serve_before.png b/doc/_static/images/develop_notebook_panel_serve_before.png
diff --git a/doc/_static/images/develop_notebook_reload_preview.png b/doc/_static/images/develop_notebook_reload_preview.png
diff --git a/doc/_static/images/develop_notebook_simple_example.png b/doc/_static/images/develop_notebook_simple_example.png
diff --git a/doc/_static/images/develop_notebook_simple_example_add_hello_again.png b/doc/_static/images/develop_notebook_simple_example_add_hello_again.png
diff --git a/doc/_static/images/develop_notebook_simple_example_add_hello_again_and_again.png b/doc/_static/images/develop_notebook_simple_example_add_hello_again_and_again.png
diff --git a/doc/_static/images/develop_notebook_simple_example_open_preview.png b/doc/_static/images/develop_notebook_simple_example_open_preview.png
diff --git a/doc/_static/images/editor_server_app.png b/doc/_static/images/editor_server_app.png
diff --git a/doc/_static/images/explore_data_perspective_chart.png b/doc/_static/images/explore_data_perspective_chart.png
diff --git a/doc/_static/images/explore_data_perspective_table.png b/doc/_static/images/explore_data_perspective_table.png
diff --git a/doc/_static/images/getting_started_app.png b/doc/_static/images/getting_started_app.png
diff --git a/doc/_static/images/hugging_face_spaces_delete.png b/doc/_static/images/hugging_face_spaces_delete.png
diff --git a/doc/_static/images/hugging_face_spaces_duplicate.png b/doc/_static/images/hugging_face_spaces_duplicate.png
diff --git a/doc/_static/images/hugging_face_spaces_duplicate_form.png b/doc/_static/images/hugging_face_spaces_duplicate_form.png
diff --git a/doc/_static/images/hugging_face_spaces_files.png b/doc/_static/images/hugging_face_spaces_files.png
diff --git a/doc/_static/images/join_community_discord.png b/doc/_static/images/join_community_discord.png
diff --git a/doc/_static/images/join_community_discourse.png b/doc/_static/images/join_community_discourse.png
diff --git a/doc/_static/images/join_community_github.png b/doc/_static/images/join_community_github.png
diff --git a/doc/_static/images/join_community_linkedin.png b/doc/_static/images/join_community_linkedin.png
diff --git a/doc/_static/images/join_community_open_source.png b/doc/_static/images/join_community_open_source.png
diff --git a/doc/_static/images/join_community_twitter.png b/doc/_static/images/join_community_twitter.png
diff --git a/doc/_static/images/jupyter_panel_preview_in_action.png b/doc/_static/images/jupyter_panel_preview_in_action.png
diff --git a/doc/_static/images/monitoring_dashboard.png b/doc/_static/images/monitoring_dashboard.png
diff --git a/doc/_static/images/notebook_inspect_param_class.png b/doc/_static/images/notebook_inspect_param_class.png
diff --git a/doc/_static/images/notebook_inspect_param_instance.png b/doc/_static/images/notebook_inspect_param_instance.png
diff --git a/doc/_static/images/notebook_inspect_print.png b/doc/_static/images/notebook_inspect_print.png
diff --git a/doc/_static/images/notebook_inspect_print_1.png b/doc/_static/images/notebook_inspect_print_1.png
diff --git a/doc/_static/images/notebook_inspect_question_mark.png b/doc/_static/images/notebook_inspect_question_mark.png
diff --git a/doc/_static/images/notebook_inspect_shift_tab.png b/doc/_static/images/notebook_inspect_shift_tab.png
diff --git a/doc/_static/images/notebook_inspect_shift_tab_link.png b/doc/_static/images/notebook_inspect_shift_tab_link.png
diff --git a/doc/_static/images/notebook_intslider_reference_doc.png b/doc/_static/images/notebook_intslider_reference_doc.png
diff --git a/doc/_static/images/panel-chat-examples.png b/doc/_static/images/panel-chat-examples.png
diff --git a/doc/_static/images/panel-serve-ipynb-app.png b/doc/_static/images/panel-serve-ipynb-app.png
diff --git a/doc/_static/images/panel-serve-ipynb-notebook.png b/doc/_static/images/panel-serve-ipynb-notebook.png
diff --git a/doc/_static/images/panel-serve-multipage-app.png b/doc/_static/images/panel-serve-multipage-app.png
diff --git a/doc/_static/images/panel-serve-py-app.png b/doc/_static/images/panel-serve-py-app.png
diff --git a/doc/_static/images/panes.png b/doc/_static/images/panes.png
diff --git a/doc/_static/images/structure_data_store_app.png b/doc/_static/images/structure_data_store_app.png
diff --git a/doc/_static/images/templates_customized_dark.png b/doc/_static/images/templates_customized_dark.png
diff --git a/doc/_static/images/templates_customized_default.png b/doc/_static/images/templates_customized_default.png
diff --git a/doc/_static/images/templates_hello_world.png b/doc/_static/images/templates_hello_world.png
diff --git a/doc/_static/images/templates_hello_world_notebook.png b/doc/_static/images/templates_hello_world_notebook.png
diff --git a/doc/_static/images/understand_load.png b/doc/_static/images/understand_load.png
diff --git a/doc/_static/images/understand_load_refresh.png b/doc/_static/images/understand_load_refresh.png
diff --git a/doc/_static/images/vscode-script.png b/doc/_static/images/vscode-script.png
diff --git a/doc/community.md b/doc/community.md
@@ -0,0 +1,75 @@
+# Community
+
+Find inspiration in the community forums, ask for help, help others, share your work, report issues, add feature requests, and contribute improvements.
+
+## Detailed discussions on Discourse
+
+:::{note}
+[Discourse](https://discourse.holoviz.org/) is the place for detailed discussions around code. Here we can ask for help, find answers to other users' questions, and showcase our work.
+
+When asking questions, please include a [Minimal, Reproducible Example](https://stackoverflow.com/help/minimal-reproducible-example) if at all possible. It will make it much, much easier to help you.
+:::
+
+Go to the [HoloViz Discourse](https://discourse.holoviz.org/) and sign up.
+
+Click [this link](https://discourse.holoviz.org/t/welcome-please-introduce-yourself/3310/) to *introduce yourself* to the community.
+
+[![HoloViz Discourse](_static/images/join_community_discourse.png)](https://discourse.holoviz.org/)
+
+## Quick chats on Discord
+
+:::{note}
+[Discord](https://discord.gg/rb6gPXbdAr) is the place for quick and live discussions.
+:::
+
+Click [this link](https://discord.gg/rb6gPXbdAr) to sign up.
+
+Then *introduce yourself* in the `introduce-yourself` channel.
+
+[![HoloViz Discourse](_static/images/join_community_discord.png)](https://discord.gg/rb6gPXbdAr)
+
+## Bugs, Features, and Contributions on Github
+
+:::{note}
+We can report bugs, ask for new features, and contribute improvements at [github.com/holoviz/panel](https://github.com/holoviz/panel).
+
+Before reporting bugs or asking for new features, please make sure they are not already in the [*Issues tracker*](https://github.com/holoviz/panel/issues).
+:::
+
+[![Github Issues](_static/images/join_community_github.png)](https://github.com/holoviz/panel/issues).
+
+Create an account by following [this guide](https://docs.github.com/en/get-started/quickstart/creating-an-account-on-github).
+
+## Announcements and Showcases on Social Media
+
+Follow Panel on [X](https://x.com/Panel_org).
+
+[![Panel on X](_static/images/join_community_twitter.png)](https://x.com/Panel_org)
+
+Follow Panel on [LinkedIn](https://www.linkedin.com/company/panel-org)
+
+[![Panel on LinkedIn](_static/images/join_community_linkedin.png)](https://www.linkedin.com/company/panel-org)
+
+## Community Resources at Awesome Panel
+
+Bookmark [Awesome Panel](https://awesome-panel.org).
+
+[![Awesome Panel](_static/images/awesome-panel.png)](https://awesome-panel.org)
+
+## Contribute
+
+Panel is an open source, community-driven project. We are nothing without the community.
+
+If you want to start contributing, check out the [Contributing Guide](https://github.com/holoviz/panel/blob/main/CONTRIBUTING.MD). Thanks.
+
+[![Panel is an Open Source, Community-driven project](_static/images/join_community_open_source.png)](https://github.com/holoviz/panel/blob/main/CONTRIBUTING.MD)
+
+## Resources
+
+- [Awesome Panel](https://awesome-panel.org).
+- [Contributing Guide](https://github.com/holoviz/panel/blob/main/CONTRIBUTING.MD)
+- [Discord](https://discord.gg/rb6gPXbdAr)
+- [Discourse](https://discourse.holoviz.org/)
+- [Github](https://github.com/holoviz/panel)
+- [LinkedIn](https://www.linkedin.com/company/panel-org)
+- [X](https://x.com/Panel_org)
diff --git a/doc/developer_guide/index.md b/doc/developer_guide/index.md
@@ -121,7 +121,7 @@ Once pyctdev is available and you are in the cloned panel repository you can set
 doit env_create -c pyviz/label/dev -c conda-forge --name=panel_dev --python=3.9
 ```
 
-Specify the desired Python version, currently Panel officially supports Python 3.8 or later. Once the environment has been created you can activate it with:
+Specify the desired Python version, currently Panel officially supports Python 3.9 or later. Once the environment has been created you can activate it with:
 
 ```bash
 conda activate panel_dev

diff --git a/doc/explanation/api/examples/outliers_declarative.md b/doc/explanation/api/examples/outliers_declarative.md
@@ -1,62 +1,80 @@
-# Simple Outlier App - Declarative API
+# Declarative API with Class-Based Approach
 
-This app is a complement to the simple app demonstrated in the [Getting Started > Build an app](../../../getting_started/build_app.md) tutorial which utilized the reactive API.
+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.
 
-The reactive API approach is very flexible, but it ties your domain-specific code (the parts about sine waves) with your widget display code. That's fine for small, quick projects or projects dominated by visualization code, but what about large-scale, long-lived projects, where the code is used in many different contexts over time, such as in large batch runs, one-off command-line usage, notebooks, and deployed dashboards?  For larger projects like that, it's important to be able to separate the parts of the code that are about the underlying domain (i.e. application or research area) from those that are tied to specific display technologies (such as Jupyter notebooks or web servers).
+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 usages, Panel supports objects declared with the separate [Param](http://param.pyviz.org) library, which provides a GUI-independent way of capturing and declaring the parameters of your objects (and dependencies between your code and those parameters), in a way that's independent of any particular application or dashboard technology. For instance, the app in [Getting Started > Build an app](../../../getting_started/build_app.md) can be captured in an object that declares the ranges and values of all parameters, as well as how to generate the plot, independently of the Panel library or any other way of interacting with the object. First, we'll copy the initial steps :
+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:
 
 ```{pyodide}
-import panel as pn
 import hvplot.pandas
 import numpy as np
-import param
 import pandas as pd
+import panel as pn
+import param
 
-pn.extension()
+PRIMARY_COLOR = "#0072B5"
+SECONDARY_COLOR = "#B54300"
+CSV_FILE = (
+    "https://raw.githubusercontent.com/holoviz/panel/main/examples/assets/occupancy.csv"
+)
 
+pn.extension(design="material")
+```
+
+```{pyodide}
+@pn.cache
+def get_data():
+    return pd.read_csv(CSV_FILE, parse_dates=["date"], index_col="date")
 
-csv_file = 'https://raw.githubusercontent.com/holoviz/panel/main/examples/assets/occupancy.csv'
-data = pd.read_csv(csv_file, parse_dates=['date'], index_col='date')
+data = get_data()
 
 data.tail()
 ```
 
 ```{pyodide}
-def view_hvplot(avg, highlight):
-    return avg.hvplot(height=300, width=400, legend=False) * highlight.hvplot.scatter(
-        color="orange", padding=0.1, legend=False
-    )
-
-def find_outliers(variable="Temperature", window=30, sigma=10, view_fn=view_hvplot):
+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 view_fn(avg, avg[outliers])
+    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, width=800, legend=False, color=PRIMARY_COLOR
+    ) * highlight.hvplot.scatter(color=SECONDARY_COLOR, padding=0.1, legend=False)
 ```
 
-Now, let's implement the declarative API approach:
+```{pyodide}
+get_plot(variable='Temperature', window=20, sigma=10)
+```
+
+Now, let's implement the declarative API approach using a `Parameterized` class:
 
 ```{pyodide}
 class RoomOccupancy(param.Parameterized):
-    variable  = param.Selector(default="Temperature", objects=list(data.columns))
-    window    = param.Integer(default=30, bounds=(1, 60))
-    sigma     = param.Number(default=10, bounds=(0, 20))
+    variable = param.Selector(default="Temperature", objects=list(data.columns))
+    window = param.Integer(default=30, bounds=(1, 60))
+    sigma = param.Number(default=10, bounds=(0, 20))
 
     def view(self):
-        return find_outliers(self.variable, self.window, self.sigma, view_fn=view_hvplot)
+        return get_plot(self.variable, self.window, self.sigma)
 
 obj = RoomOccupancy()
 obj
 ```
 
-The `RoomOccupancy` class and the `obj` instance have no dependency on Panel, Jupyter, or any other GUI or web toolkit; they simply declare facts about a certain domain (such as that smoothing requires window and sigma parameters, and that window is an integer greater than 0 and sigma is a positive real number).  This information is then enough for Panel to create an editable and viewable representation for this object without having to specify anything that depends on the domain-specific details encapsulated in `obj`:
-
+The `RoomOccupancy` class and the `obj` instance have no direct dependency on Panel, Jupyter, or any other GUI toolkit. They solely declare facts about a specific domain, such as the parameters required for smoothing. This information is sufficient for Panel to create an interactive representation without needing domain-specific details encapsulated in `obj`:
 
 ```{pyodide}
 pn.Column(obj.param, obj.view)
 ```
 
-To support a particular domain, you can create hierarchies of such classes encapsulating all the parameters and functionality you need across different families of objects, with both parameters and code inheriting across the classes as appropriate, all without any dependency on a particular GUI library or even the presence of a GUI at all.  This approach makes it practical to maintain a large codebase, all fully displayable and editable with Panel, in a way that can be maintained and adapted over time. See the [Attractors Panel app](https://examples.pyviz.org/attractors/attractors_panel.html) ([source](https://github.com/holoviz-topics/examples/tree/main/attractors)) for a more complex illustration of this approach, and the Panel codebase itself for the ultimate demonstration of using Param throughout a codebase!
+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.