Update docs about pn.serve per user state (#2849)

* Improve documentation about pn.serve

* Update overview

examples/user_guide/Deploy_and_Export.ipynb

@@ -193,7 +193,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Display in the Python REPL\n",
+    "## Launching a server dynamically\n",
+    "\n",
+    "The CLI `panel serve` command described below is usually the best approach for deploying applications. However when working on the REPL or embedding a Panel/Bokeh server in another application it is sometimes useful to dynamically launch a server, either using the `.show` method or using the `pn.serve` function.\n",
+    "\n",
+    "### Previewing an application\n",
     "\n",
     "Working from the command line will not automatically display rich representations inline as in a notebook, but you can still interact with your Panel components if you start a Bokeh server instance and open a separate browser window using the ``show`` method. The method has the following arguments:\n",
     "\n",
@@ -228,15 +232,35 @@
     "If you want to serve more than one app on a single server you can use the ``pn.serve`` function. By supplying a dictionary where the keys represent the URL slugs and the values must be either Panel objects or functions returning Panel objects you can easily launch a server with a number of apps, e.g.:\n",
     "\n",
     "```python\n",
-    "pn.serve({'markdown': '# This is a Panel app', 'json': pn.pane.JSON({'abc': 123})})\n",
+    "pn.serve({\n",
+    "    'markdown': '# This is a Panel app',\n",
+    "    'json': pn.pane.JSON({'abc': 123})\n",
+    "})\n",
+    "```\n",
+    "\n",
+    "Note that when you serve an object directly all sessions will share the same state, i.e. the parameters of all components will be synced across sessions such that the change in a widget by one user will affect all other users. Therefore you will usually want to wrap your app in a function, ensuring that each user gets a new instance of the application:\n",
+    "\n",
+    "```python\n",
+    "\n",
+    "def markdown_app():\n",
+    "    return '# This is a Panel app'\n",
+    "\n",
+    "def json_app():\n",
+    "    return pn.pane.JSON({'abc': 123})\n",
+    "\n",
+    "pn.serve({\n",
+    "    'markdown': markdown_app,\n",
+    "    'json': json_app\n",
+    "})\n",
     "```\n",
     "\n",
     "You can customize the HTML title of each application by supplying a dictionary where the keys represent the URL slugs and the values represent the titles, e.g.:\n",
     "\n",
     "```python\n",
-    "pn.serve(\n",
-    "    {'markdown': '# This is a Panel app', 'json': pn.pane.JSON({'abc': 123})},\n",
-    "    title={'markdown': 'A Markdown App', 'json': 'A JSON App'}\n",
+    "pn.serve({\n",
+    "    'markdown': '# This is a Panel app',\n",
+    "    'json': pn.pane.JSON({'abc': 123})\n",
+    "}, title={'markdown': 'A Markdown App', 'json': 'A JSON App'}\n",
     ")\n",
     "```\n",
     "\n",

examples/user_guide/Overview.ipynb

@@ -27,13 +27,13 @@
     "\n",
     "Panel is a very flexible system that supports many different usage patterns, via multiple application programming interfaces (APIs).  Each API has its own advantages and disadvantages, and is suitable for different tasks and ways of working. The [API user guide](APIs.ipynb) goes through each of the APIs in detail, comparing their pros and cons and providing recommendations on when to use each.\n",
     "\n",
-    "#### [``interact``](./Interact.ipynb)\n",
+    "#### [Reactive functions](./APIs.ipynb#Reactive-Functions)\n",
     "\n",
-    "The ``interact`` API will be familiar to ipywidgets users; it provides a very simple API to define an interactive view of the results of a Python function. This approach works by declaring functions whose arguments will be inspected to infer a set of widgets. Changing any of the resulting widgets causes the function to be re-run, updating the displayed output. This approach makes it extremely easy to get started and also easy to rearrange and reconfigure the resulting plots and widgets, but it may not be suited to more complex scenarios. See the [Interact user guide](./Interact.ipynb) for more detail.\n",
+    "Defining a reactive function using the ``pn.bind`` function or ``pn.depends`` decorator provides an explicit way to link specific inputs (such as the value of a widget) to some computation in a function, reactively updating the output of the function whenever the parameter changes. This approach is a highly convenient, intuitive, and flexible way of building interactive UIs.\n",
     "\n",
-    "#### Reactive functions\n",
+    "#### [``interact``](./Interact.ipynb)\n",
     "\n",
-    "Defining a reactive function using the ``pn.depends`` decorator provides an explicit way to link specific inputs (such as the value of a widget) to some computation in a function, reactively updating the output of the function whenever the parameter changes. This approach is a highly convenient, intuitive, and flexible way of building interactive UIs.\n",
+    "The ``interact`` API will be familiar to ipywidgets users; it provides a very simple API to define an interactive view of the results of a Python function. This approach works by declaring functions whose arguments will be inspected to infer a set of widgets. Changing any of the resulting widgets causes the function to be re-run, updating the displayed output. This approach makes it extremely easy to get started and also easy to rearrange and reconfigure the resulting plots and widgets, but it may not be suited to more complex scenarios. See the [Interact user guide](./Interact.ipynb) for more detail.\n",
     "\n",
     "#### [``Param``](./Param.ipynb)\n",
     "\n",
@@ -78,17 +78,17 @@
     "\n",
     "> The ``.app()`` method present on all viewable Panel objects allows displaying a Panel server process inline in a notebook, which can be useful for debugging a standalone server interactively.\n",
     "\n",
-    "#### Python REPL\n",
+    "#### Python REPL and embedding a server\n",
     "\n",
-    "Even when working in a Python REPL that does not support rich-media output (e.g. in a text-based terminal), a panel can be still be launched in a browser tab:\n",
+    "When working in a Python REPL that does not support rich-media output (e.g. in a text-based terminal) or when embedding a Panel application in another tool, a panel can be launched in a browser tab using:\n",
     "\n",
     "##### ``.show()``\n",
     "\n",
     "> The ``.show()`` method is present on all viewable Panel objects and starts a server instance then opens a browser tab to point to it. To support working remotely, a specific port on which to launch the app can be supplied.\n",
     "\n",
     "##### ``pn.serve()``\n",
     "\n",
-    ">Similar to .show() on a Panel object but allows serving one or more Panel apps on a single server. Supplying a dictionary mapping from the URL slugs to the individual Panel objects being served allows launching multiple apps at once. \n",
+    ">Similar to .show() on a Panel object but allows serving one or more Panel apps on a single server. Supplying a dictionary mapping from the URL slugs to the individual Panel objects being served allows launching multiple apps at once. Note that to ensure that each user gets separate session state you should wrap your app in a function which returns the Panel component to render. This ensures that whenever a new user visits the application a new instance of the application can be created.\n",
     "\n",
     "#### Command line\n",
     "\n",