From 3e149a2dff98118695dee0ec9a2096b61df6dd2d Mon Sep 17 00:00:00 2001 From: MarcSkovMadsen Date: Sat, 20 Jan 2024 16:23:17 +0000 Subject: [PATCH] refactor --- doc/tutorials/beginner/develop_editor.md | 2 +- .../{ => beginner}/develop_notebook.md | 30 +++++++++---------- .../{ => beginner}/display_pn_panel.md | 20 ++++++------- doc/tutorials/index.md | 12 ++++---- 4 files changed, 32 insertions(+), 32 deletions(-) rename doc/tutorials/{ => beginner}/develop_notebook.md (85%) rename doc/tutorials/{ => beginner}/display_pn_panel.md (85%) diff --git a/doc/tutorials/beginner/develop_editor.md b/doc/tutorials/beginner/develop_editor.md index c39d6e3dcc..aacd3e3be0 100644 --- a/doc/tutorials/beginner/develop_editor.md +++ b/doc/tutorials/beginner/develop_editor.md @@ -1,6 +1,6 @@ # Develop in an Editor -In this section you will learn the basics of developing efficiently in an editor: +In this section you will learn the basics of developing Panel apps in an editor: - serve your app with *autoreload* using `panel serve app.py --autoreload` - display the app in a *simple* browser tab inside your editor if possible diff --git a/doc/tutorials/develop_notebook.md b/doc/tutorials/beginner/develop_notebook.md similarity index 85% rename from doc/tutorials/develop_notebook.md rename to doc/tutorials/beginner/develop_notebook.md index 393c193e81..f5b3f2fb31 100644 --- a/doc/tutorials/develop_notebook.md +++ b/doc/tutorials/beginner/develop_notebook.md @@ -1,6 +1,6 @@ # Develop in a Notebook -In this guide you will learn how to develop efficiently in a notebook: +In this section you will learn the basics of developing Panel apps efficiently in a notebook: - Preview your notebook app in Jupyter lab with the *Jupyter Panel Preview*. - Serve your notebook app with autoreload using `panel serve app.ipynb --autoreload`. @@ -39,7 +39,7 @@ pip install matplotlib numpy A simple notebook file containing a Panel app could look like. -![Panel Notebook Example App](../_static/images/develop_notebook_simple_example.png) +![Panel Notebook Example App](../../_static/images/develop_notebook_simple_example.png) Start from an empty notebook named `app.ipynb`. @@ -63,7 +63,7 @@ Run the cells if you have not already done it. It should look like -![Panel Notebook App](../_static/images/develop_notebook_simple_example.png) +![Panel Notebook App](../../_static/images/develop_notebook_simple_example.png) :::{admonition} Note The code in the notebook refer to @@ -82,7 +82,7 @@ Click the *Jupyter Panel Preview* icon. You will see the app launching in a separate window on the right. -![Jupyter Panel Preview](../_static/images/develop_notebook_simple_example_open_preview.png) +![Jupyter Panel Preview](../../_static/images/develop_notebook_simple_example_open_preview.png) :::{admonition} Note You will notice that "Hello Again" is not displayed in the app preview. That is because `pn.panel("Hello Again")` has not been added to the app. You can do that by marking it `.servable()`. @@ -98,11 +98,11 @@ Save the notebook. Click the *Reload Preview* button in the *Jupyter Panel Preview*. -![Reload Preview Button](../_static/images/develop_notebook_reload_preview.png) +![Reload Preview Button](../../_static/images/develop_notebook_reload_preview.png) The *preview* will reload and look like -![Reloaded Preview](../_static/images/develop_notebook_simple_example_add_hello_again.png) +![Reloaded Preview](../../_static/images/develop_notebook_simple_example_add_hello_again.png) :::{admonition} Note To enable a more efficient workflow you can check the *Render on Save* checkbox. This will *auto reload* your app when the notebook is saved. @@ -120,7 +120,7 @@ Save the notebook. The preview will automatically reload and look like -![Automatically Reloaded Preview](../_static/images/develop_notebook_simple_example_add_hello_again_and_again.png) +![Automatically Reloaded Preview](../../_static/images/develop_notebook_simple_example_add_hello_again_and_again.png) Watch the video below to learn how the techniques above can be used to develop a more advanced app. @@ -186,7 +186,7 @@ Open [http://localhost:5006/app](http://localhost:5006/app) in a browser. It would look something like -![Panel served notebook app](../_static/images/develop_notebook_panel_serve_before.png) +![Panel served notebook app](../../_static/images/develop_notebook_panel_serve_before.png) Now change the @@ -225,17 +225,17 @@ Write `pn.widgets.IntSlider` in a cell and press `SHIFT+Tab`. It should look like -![Inspect a Panel component using SHIFT+Tab](../_static/images/notebook_inspect_shift_tab.png) +![Inspect a Panel component using SHIFT+Tab](../../_static/images/notebook_inspect_shift_tab.png) Use the mouse to scroll down until you find the *Example* code snippet and *Reference* link. -![Inspect a Panel component using SHIFT+Tab](../_static/images/notebook_inspect_shift_tab_link.png) +![Inspect a Panel component using SHIFT+Tab](../../_static/images/notebook_inspect_shift_tab_link.png) Click the *Reference* link https://panel.holoviz.org/reference/widgets/IntSlider.html It should look like -[![IntSlider Reference Documentation](../_static/images/notebook_intslider_reference_doc.png)](https://panel.holoviz.org/reference/widgets/IntSlider.html) +[![IntSlider Reference Documentation](../../_static/images/notebook_intslider_reference_doc.png)](https://panel.holoviz.org/reference/widgets/IntSlider.html) :::{admonition} Note It is a great idea to use the *Example* code snippets and *Reference* links to speed up your workflow. @@ -268,7 +268,7 @@ Run the cells if you have not already done it. It should look like -![Inspect a Panel component](../_static/images/notebook_inspect_print.png) +![Inspect a Panel component](../../_static/images/notebook_inspect_print.png) :::{admonition} Note By printing *layout* components like `Column` you can understand how its composed. This enables you to *access* the subcomponents of the layout. @@ -288,7 +288,7 @@ Run the new cells if you have not already done it. It should look like -![Inspect a Panel component](../_static/images/notebook_inspect_print_1.png) +![Inspect a Panel component](../../_static/images/notebook_inspect_print_1.png) ## Inspect a Components Parameters using `.param` @@ -310,7 +310,7 @@ Run the code cells if you have not already done it. It should look like -![Inspect a Panel component class with .param](../_static/images/notebook_inspect_param_class.png) +![Inspect a Panel component class with .param](../../_static/images/notebook_inspect_param_class.png) :::{admonition} Note - The `.param` table shows you the *default* parameter values of the `IntSlider` class. For example the *default* value of `align` is `'start'`. @@ -327,7 +327,7 @@ Run the code cell It should look like -![Inspect a Panel component instance with .param](../_static/images/notebook_inspect_param_instance.png) +![Inspect a Panel component instance with .param](../../_static/images/notebook_inspect_param_instance.png) :::{admonition} Note - In the picture above you see the *actual* parameter values of the `IntSlider` instance. For example the *actual* value of `align` is `'end'`. diff --git a/doc/tutorials/display_pn_panel.md b/doc/tutorials/beginner/display_pn_panel.md similarity index 85% rename from doc/tutorials/display_pn_panel.md rename to doc/tutorials/beginner/display_pn_panel.md index f28d8dcb86..6c978993d5 100644 --- a/doc/tutorials/display_pn_panel.md +++ b/doc/tutorials/beginner/display_pn_panel.md @@ -71,7 +71,7 @@ component.servable() ``` :::{admonition} Note -You cell or terminal output should contain `Markdown(str)`. It means `pn.panel` has picked the [`Markdown` *pane*](../reference/panes/Markdown.md) to display the `str` object. +You cell or terminal output should contain `Markdown(str)`. It means `pn.panel` has picked the [`Markdown` *pane*](../../reference/panes/Markdown.md) to display the `str` object. ::: Lets verify that *markdown strings* are actually displayed and rendered nicely @@ -128,10 +128,10 @@ print(component) component.servable() ``` -Please notice `pn.panel` chose a [`Matplotlib` pane](../reference/panes/Matplotlib.md) to display the Matplotlib figure. +Please notice `pn.panel` chose a [`Matplotlib`](../../reference/panes/Matplotlib.md) pane to display the Matplotlib figure. :::{admonition} Note -In the code example above we provide arguments to `pn.panel`. These will be applied to the *pane* selected by `pn.panel` to display the object. In this example the [`Matplotlib` pane](../reference/panes/Matplotlib.md) is selected. +In the code example above we provide arguments to `pn.panel`. These will be applied to the *pane* selected by `pn.panel` to display the object. In this example the [`Matplotlib`](../../reference/panes/Matplotlib.md) pane is selected. The arguments `dpi` and `tight` would not make sense if a string was provided as argument to `pn.panel`. In that case the exception `TypeError: Markdown.__init__() got an unexpected keyword argument 'dpi'` would be raised. ::: @@ -160,7 +160,7 @@ print(component) component.servable() ``` -Please notice that `pn.panel` chose a [`HoloViews` pane](../reference/panes/HoloViews.md) to display the hvPlot figure. +Please notice that `pn.panel` chose a [`HoloViews`](../../reference/panes/HoloViews.md) pane to display the hvPlot figure. ## Display a Plotly plot @@ -188,7 +188,7 @@ print(component) component.servable() ``` -Please notice that `pn.panel` chose a [`Plotly` pane](../reference/panes/Plotly.md) to display the Plotly figure. +Please notice that `pn.panel` chose a [`Plotly`](../../reference/panes/Plotly.md) pane to display the Plotly figure. :::{admonition} Note We must add `"plotly"` as an argument to `pn.extension` in the example to load the Plotly Javascript dependencies in the browser. @@ -220,7 +220,7 @@ print(component) component.servable() ``` -Please notice that `pn.panel` chose to display the objects using a [`JSON` pane](../reference/panes/JSON.md), ['PNG' pane](../reference/panes/PNG.md) and an [`Audio` pane](../reference/panes/Audio.md) +Please notice that `pn.panel` chose to display the objects using the [`JSON`](../../reference/panes/JSON.md), [`PNG`](../../reference/panes/PNG.md) and [`Audio`](../../reference/panes/Audio.md) panes respectively. ## Display (almost) any Python object in a layout @@ -242,7 +242,7 @@ component.servable() ``` :::{admonition} Note -When Python objects are given as an argument to a Panel [Layout](../reference/index.md#layouts) like [`pn.Column`](../reference/layouts/Column.md), then `pn.Column` will automatically apply `pn.panel` to the objects for you. +When Python objects are given as an argument to a Panel [Layout](../../reference/index.md#layouts) like [`pn.Column`](../../reference/layouts/Column.md), then `pn.Column` will automatically apply `pn.panel` to the objects for you. ::: Please notice that the image of the dice is very high. To finetune the way it is displayed we can use `pn.panel`. @@ -267,9 +267,9 @@ component.servable() ## Use a specific Pane if performance is key :::{admonition} Note -`pn.panel` is an easy to use and flexible **helper function** that will convert an object into a [*Pane*](../reference/index.md#panes). +`pn.panel` is an easy to use and flexible **helper function** that will convert an object into a [*Pane*](../../reference/index.md#panes). -More specifically `pn.panel` resolves the appropriate *representation* for an object by checking all [*Pane*](../reference/index.md#panes) object types available and then ranking them by priority. When passing a string (for instance) there are many representations, but the PNG pane takes precedence if the string is a valid URL or local file path ending in ".png". +More specifically `pn.panel` resolves the appropriate *representation* for an object by checking all [*Pane*](../../reference/index.md#panes) object types available and then ranking them by priority. When passing a string (for instance) there are many representations, but the [`PNG`](../../reference/panes/PNG.md) pane takes precedence if the string is a valid URL or local file path ending in `.png`. Resolving the appropriate *representation* for an object takes time. So if performance is key you should specify the specific type of Pane to use directly. I.e. use `pn.pane.Matplotlib(fig)` instead of `pn.panel(fig)`. ::: @@ -322,4 +322,4 @@ In this guide you have learned to display Python objects very easily and flexibl ### Other -- [Pane Gallery](../reference/index.md#panes) +- [Pane Gallery](../../reference/index.md#panes) diff --git a/doc/tutorials/index.md b/doc/tutorials/index.md index 35c8eb6732..3629c3cbd9 100644 --- a/doc/tutorials/index.md +++ b/doc/tutorials/index.md @@ -28,18 +28,18 @@ Learn how to serve an app with autoreload using the `panel serve` command. :link: beginner/develop_editor :link-type: doc -Learn to develop efficiently with Panel in an editor efficiently +Learn the basics of developing Panel apps in an editor ::: :::{grid-item-card} {octicon}`note;2.5em;sd-mr-1` Develop in a Notebook -:link: develop_editor +:link: beginner/develop_notebook :link-type: doc -Learn how to develop efficiently with Panel in a notebook. +Learn the basics of developing Panel apps in a notebook ::: :::{grid-item-card} {octicon}`zap;2.5em;sd-mr-1` Display objects with `pn.panel` -:link: display_pn_panel +:link: beginner/display_pn_panel :link-type: doc Learn how to display objects easily and flexibly with `pn.panel`. @@ -103,8 +103,8 @@ In this section we will review different approaches for styling components, from beginner/panel_serve beginner/develop_editor -develop_notebook -display_pn_panel +beginner/develop_notebook +beginner/display_pn_panel param components interactivity