Move best practices section

doc/how_to/best_practices/index.md

@@ -5,7 +5,7 @@ This section is to provide a checklist of best practices for developing with Pan
 ::::{grid} 1 2 2 3
 :gutter: 1 1 1 2
 
-:::{grid-item-card} {octicon}`gear;2.5em;sd-mr-1 sd-animate-grow50` Dev Experience
+:::{grid-item-card} {octicon}`gear;2.5em;sd-mr-1 sd-animate-grow50` Developer Experience
 :link: dev_experience
 :link-type: doc
 

doc/how_to/index.md

@@ -121,27 +121,6 @@ How to access and manipulate state related to the user session, HTTP request and
 
 ::::
 
-## Apply best practices
-
-::::{grid} 1 2 2 3
-:gutter: 1 1 1 2
-
-:::{grid-item-card} {octicon}`pulse;2.5em;sd-mr-1 sd-animate-grow50` For dev experience
-:link: best_practices/index/dev_experience
-:link-type: doc
-
-A checklist of best practices for developing with Panel.
-:::
-
-
-:::{grid-item-card} {octicon}`pulse;2.5em;sd-mr-1 sd-animate-grow50` For user experience
-:link: best_practices/index/user_experience
-:link-type: doc
-
-A checklist of best practices for designing Panel applications.
-:::
-
-::::
 ## Extending Panel
 
 ::::{grid} 1 2 2 3
@@ -210,6 +189,13 @@ How to cache data across sessions and memoize the output of functions.
 How to improve the scalability of your Panel application.
 :::
 
+:::{grid-item-card} {octicon}`pulse;2.5em;sd-mr-1 sd-animate-grow50` Best Practices
+:link: best_practices/index
+:link-type: doc
+
+A checklist of best practices for improving the development and user experience with Panel.
+:::
+
 :::{grid-item-card} {octicon}`shield-check;2.5em;sd-mr-1 sd-animate-grow50` Add authentication
 :link: authentication/index
 :link-type: doc
@@ -303,7 +289,6 @@ prepare_to_develop
 build_apps
 use_specialized_uis
 manage_session_tasks
-best_practices
 extending_panel
 test_and_debug
 prepare_to_share

doc/how_to/prepare_to_share.md

@@ -14,5 +14,6 @@ Apply Templates<templates/index>
 Improve Performance<performance/index>
 Cache Data<caching/index>
 Improve Scalability<concurrency/index>
+Best Practices <best_practices/index>
 Add Authentication<authentication/index>
 ```

examples/how_to/best_practices/dev_experience.ipynb

@@ -1,12 +1,5 @@
 {
  "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Dev Experience"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -17,29 +10,22 @@
     "\n",
     "import param\n",
     "import panel as pn\n",
+    "\n",
     "pn.extension()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Understanding Labels\n",
+    "The best practices described on this page serve as a checklist of items to keep in mind as you are developing your application. They include items we see users frequently get confused about or things that are easily missed but can make a big difference to the user experience of your application(s).\n",
     "\n",
+    ":::{note}\n",
     "- Good: recommended, works.\n",
     "- Okay: works (with intended behavior), potentially inefficient.\n",
     "- Bad: Deprecated (may or may not work), just don't do it.\n",
     "- Wrong: Not intended behavior, won't really work.\n",
-    "\n",
-    "## Table of Contents\n",
-    "\n",
-    "- [Bind on reference value, not value](#bind-on-reference-value-not-value)\n",
-    "- [Inherit from `pn.viewer.Viewer`](#inherit-from-pnviewerviewer)\n",
-    "- [Build widgets from parameters](#build-widgets-from-parameters)\n",
-    "- [Show templates in notebooks](#show-templates-in-notebooks)\n",
-    "- [Yield to show intermediate values](#yield-to-show-intermediate-values)\n",
-    "- [Watch side effects](#watch-side-effects)\n",
-    "- [Refreshing layout objects](#refreshing-layout-objects)"
+    ":::"
    ]
   },
   {
@@ -347,7 +333,7 @@
    "source": [
     "#### Wrong\n",
     "\n",
-    "Widgets should not be used as parameters."
+    "Widgets should not be used as parameters since all instances of the class will share the widget class:"
    ]
   },
   {
@@ -360,7 +346,7 @@
     "\n",
     "    width = pn.widgets.IntSlider()\n",
     "    height = pn.widgets.IntInput()\n",
-    "    color = pn.widgets.ColorPicker()\n"
+    "    color = pn.widgets.ColorPicker()"
    ]
   },
   {
@@ -440,7 +426,8 @@
     "    main=[...],\n",
     "    sidebar=[...],\n",
     ")\n",
-    "template"
+    "\n",
+    "template;"
    ]
   },
   {
@@ -550,7 +537,7 @@
     "\n",
     "#### Good\n",
     "\n",
-    "To refresh a layout's objects, set `objects`."
+    "Updating the `objects` on a layout should be done via the methods on the layout itself:"
    ]
   },
   {
@@ -563,7 +550,9 @@
     "    print(f\"Got new {[pane.object for pane in event.new]}\")\n",
     "\n",
     "col = pn.Column(\"a\", \"b\")\n",
-    "pn.bind(print_objects, col.param.objects, watch=True)\n",
+    "\n",
+    "col.param.watch(print_objects, 'objects')\n",
+    "\n",
     "col"
    ]
   },
@@ -573,7 +562,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "col.objects = [\"c\", *col.objects[1:]]"
+    "col[:] = [\"c\", *col.objects[1:]]"
    ]
   },
   {
@@ -595,7 +584,9 @@
     "    print(f\"Got new {event.new}\")\n",
     "\n",
     "col = pn.Column(\"a\", \"b\")\n",
+    "\n",
     "col.param.watch(print_objects, \"objects\")\n",
+    "\n",
     "col"
    ]
   },
@@ -627,7 +618,9 @@
     "    print(f\"Got new {[pane.object for pane in event.new]}\")\n",
     "\n",
     "col = pn.Column(\"a\", \"b\")\n",
-    "pn.bind(print_objects, col.param.objects, watch=True)\n",
+    "\n",
+    "col.param.watch(print_objects, \"objects\")\n",
+    "\n",
     "col"
    ]
   },
@@ -649,5 +642,5 @@
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

examples/how_to/best_practices/user_experience.ipynb

@@ -1,12 +1,5 @@
 {
  "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# User Experience"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -27,24 +20,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Understanding Labels\n",
+    "The best practices described on this page serve as a checklist of items to keep in mind as you are developing your application. They include items we see users frequently get confused about or things that are easily missed but can make a big difference to the user experience of your application(s).\n",
     "\n",
+    ":::{note}\n",
     "- Good: recommended, works.\n",
     "- Okay: works (with intended behavior), potentially inefficient.\n",
     "- Bad: Deprecated (may or may not work), just don't do it.\n",
     "- Wrong: Not intended behavior, won't really work.\n",
-    "\n",
-    "## Table of Contents\n",
-    "\n",
-    "- [Update params effectively](#update-params-effectively)\n",
-    "- [Throttle slider callbacks](#throttle-slider-callbacks)\n",
-    "- [Defer expensive operations](#defer-expensive-operations)\n",
-    "- [Show indicator while computing](#show-indicator-while-computing)\n",
-    "- [Manage exceptions gracefully](#manage-exceptions-gracefully)\n",
-    "- [Cache values for speed](#cache-values-for-speed)\n",
-    "- [Preserve axes ranges on update](#preserve-axes-ranges-on-update)\n",
-    "- [FlexBox instead of Column/Row](#flexbox-instead-of-columnrow)\n",
-    "- [Reuse objects for efficiency](#reuse-objects-for-efficiency)"
+    ":::"
    ]
   },
   {
@@ -56,6 +39,7 @@
     "#### Good\n",
     "\n",
     "Use `obj.param.update`:\n",
+    "\n",
     "- to update multiple parameters on an object simultaneously\n",
     "- as a context manager to temporarily set values, restoring original values on completion"
    ]
@@ -200,7 +184,7 @@
    "source": [
     "#### Good\n",
     "\n",
-    "Its easy defer the execution of all bound and displayed functions with `pn.extension(defer_load=True)`."
+    "Its easy defer the execution of all bound and displayed functions with `pn.extension(defer_load=True)` (note this applies to served applications, not to interactive notebook environments):"
    ]
   },
   {
@@ -240,9 +224,7 @@
     "\n",
     "def onload():\n",
     "    time.sleep(1)  # simulate expensive operations\n",
-    "    layout.objects = [\n",
-    "        \"Welcome to this app!\",\n",
-    "    ]\n",
+    "    layout[:] = [\"Welcome to this app!\"]\n",
     "\n",
     "layout = pn.Column(\"Loading...\")\n",
     "display(layout)\n",
@@ -578,5 +560,5 @@
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }