Cleanup docs (#3879)

.github/workflows/docs.yaml

@@ -58,7 +58,7 @@ jobs:
       - name: conda setup
         run: |
           conda config --prepend channels bokeh/label/dev
-          conda create -n test-environment python=3.8 pyctdev
+          conda create -n test-environment python=3.9 pyctdev
       - uses: actions/setup-node@v2
         with:
           node-version: '15'
@@ -111,7 +111,7 @@ jobs:
         run: |
           eval "$(conda shell.bash hook)"
           conda activate test-environment
-          panel convert examples/gallery/streaming/*.ipynb examples/gallery/dynamic/*.ipynb examples/gallery/param/*.ipynb --to pyodide-worker --out ./builtdocs/pyodide/
+          panel convert examples/gallery/**/*.ipynb --to pyodide-worker --out ./builtdocs/pyodide/
       - name: git status and git diff
         run: |
           git status

doc/user_guide/APIs.md

@@ -41,13 +41,13 @@ pn.extension()
 
 The `pn.bind` reactive programming API is very similar to the ``interact`` function but is more explicit about widget selection and layout. `pn.bind` requires the programmer to select and configure widgets explicity and to lay out components explicitly, without relying on inference of widget types and ranges and without any default layouts. Specifying those aspects explicitly provides more power and control, but does typically take a bit more code and more knowledge of widget and layout components than using `interact` does. Once widgets have been bound to a reactive function, you can lay out the bound function and the widgets in any order or combination you like, including across Jupyter notebook cells if desired.
 
-#### Pros:
+### Pros:
 
 + Very clear mapping from widgets to the arguments of the function.
 + Very explicit layout of each of the different components.
 + Like `interact`, doesn't typically require modifying existing visualization code.
 
-#### Cons:
+### Cons:
 
 - Typically requires a bit more code than `interact`
 
@@ -109,21 +109,21 @@ This alternative way of specifying the same app lets you declare the dependency
 
 ## Interact Functions
 
-The ``interact`` function will automatically generate a UI (including widgets) by inspecting the arguments of the function given to it, or by using additional hints you provide in the ``interact`` function call. If you have worked with the [``ipywidgets``](https://github.com/jupyter-widgets/ipywidgets) package you may already be familiar with this approach. (In fact, the Panel interact function is modeled on the one from ipywidgets, making it simpler to port code between the two platforms.) The basic idea is that given a function that returns some object, Panel will inspect the arguments to that function, try to infer appropriate widgets for those arguments, and then re-run that function to update the output whenever one of the widgets generates an event. For more detail on how interact creates widgets and other ways of using it, see the Panel [interact user guide](./interact.md).  This section instead focuses on when and why to use this API, laying out its benefits and drawbacks.
+The ``interact`` function will automatically generate a UI (including widgets) by inspecting the arguments of the function given to it, or by using additional hints you provide in the ``interact`` function call. If you have worked with the [``ipywidgets``](https://github.com/jupyter-widgets/ipywidgets) package you may already be familiar with this approach. (In fact, the Panel interact function is modeled on the one from ipywidgets, making it simpler to port code between the two platforms.) The basic idea is that given a function that returns some object, Panel will inspect the arguments to that function, try to infer appropriate widgets for those arguments, and then re-run that function to update the output whenever one of the widgets generates an event. For more detail on how interact creates widgets and other ways of using it, see the Panel [interact user guide](./Interact.md).  This section instead focuses on when and why to use this API, laying out its benefits and drawbacks.
 
 The main benefit of this approach is convenience and ease of use.  You start by writing some function that returns an object, be that a plot, a dataframe, or anything else that Panel can render. Then with a single call to `pn.interact()`, you can immediately get an interactive UI, without ever instantiating any widgets or wiring up any callbacks explicitly. Unlike ipywidgets, the ``pn.interact`` call will return a Panel. This Panel can then be further modified by laying out the widgets and output separately, or combining these components with other panes. Even though `pn.interact` itself is limited in flexibility compared to the rest of Panel, you can still unpack and reconfigure the results from it to generate fairly complex GUIs in very little code.
 
-#### Pros:
+### Pros:
 
 + Easy to use (or at least easy to get started!).
 + Doesn't typically require modifying existing visualization code.
 
-#### Cons:
+### Cons:
 
 - Most of the behavior is implicit, with magic happening by introspection, making it difficult to see how to modify the appearance or functionality of the resulting object.
 - Customizing the layout requires indexing into the panel returned by `interact`.
 
-The simplest `interact` call can be a one-liner, but here we'll show an example of intermediate complexity so that you get a good idea of what `interact` can do in practice. In this code, ``pn.interact`` infers the initial value for `x` and `y` from the `autompg_plot` function default arguments and their widget type and range from the `columns` list provided to `interact`. `interact` wouldn't normally put up a color widget because it would have no way of knowing that this string-type argument represents an RGB color, and so here we explicitly create a color-picker widget and pass that as the value for the color so that we can control the color as well. Finally, we unpack the result from `interact` and rearrange it in a different layout with a title, to create the final app. See the Panel [interact user guide](./interact.md) for even simpler examples along with details about how to control the widgets and how to rearrange the layout.
+The simplest `interact` call can be a one-liner, but here we'll show an example of intermediate complexity so that you get a good idea of what `interact` can do in practice. In this code, ``pn.interact`` infers the initial value for `x` and `y` from the `autompg_plot` function default arguments and their widget type and range from the `columns` list provided to `interact`. `interact` wouldn't normally put up a color widget because it would have no way of knowing that this string-type argument represents an RGB color, and so here we explicitly create a color-picker widget and pass that as the value for the color so that we can control the color as well. Finally, we unpack the result from `interact` and rearrange it in a different layout with a title, to create the final app. See the Panel [interact user guide](./Interact.md) for even simpler examples along with details about how to control the widgets and how to rearrange the layout.
 
 
 ```{pyodide}
@@ -139,12 +139,12 @@ The [Param](http://param.pyviz.org) library allows expressing the parameters of
 
 The parameterized approach is a powerful way to encapsulate computation in self-contained classes, taking advantage of object-oriented programming patterns. It also makes it possible to express a problem completely independently from Panel or any other GUI code, while still getting a GUI for free as a last step. For more detail on using this approach see the [Param user guide](./Param.md).
 
-Pros:
+### Pros:
 
 + Declarative way of expressing parameters and dependencies between parameters and computation
 + The resulting code is not tied to any particular GUI framework and can be used in other contexts as well
 
-Cons:
+### Cons:
 
 - Requires writing classes
 - Less explicit about widgets to use for each parameter; can be harder to customize behavior than if widgets are instantiated explicitly
@@ -176,11 +176,11 @@ The callback API in panel is the lowest-level approach, affording the greatest a
 
 For more details on defining callbacks see the [Links user guide](./Links.md).
 
-#### Pros:
+### Pros:
 
 + Complete and modular control over specific events
 
-#### Cons:
+### Cons:
 
 - Complexity grows very quickly with the number of callbacks
 - Have to handle initializing the plots separately

doc/user_guide/Components.md

@@ -1,4 +1,4 @@
-# Components
+# Component overview
 
 Panel provides a wide range of components for easily composing panels, apps, and dashboards both in the notebook and as standalone apps. The components can be broken down into three broad classes of objects:
 

doc/user_guide/Customization.md

@@ -10,7 +10,7 @@ Panel objects are built on top of [Param](https://param.pyviz.org), which allows
 
 ## Styling Components
 
-#### ``css_classes``
+### ``css_classes``
 
 The ``css_classes`` parameter allows associating a Panel component with one or more CSS classes. CSS styles can be embedded in raw form or by referencing an external .css file by providing each to the panel extension using the ``raw_css`` and ``css_files`` arguments; both should be supplied as lists. Outside the notebook or if we want to add some CSS in an external module or library, we can simply append to the ``pn.config.raw_css`` and ``pn.config.js_files`` config parameters.
 
@@ -40,7 +40,7 @@ pn.Column(
 css_classes=['panel-widget-box'])
 ```
 
-#### ``background``
+### ``background``
 
 In case we simply want to give the component a background we can define one as a hex string:
 
@@ -49,7 +49,7 @@ In case we simply want to give the component a background we can define one as a
 pn.pane.HTML(background='#f307eb', width=100, height=100)
 ```
 
-#### `loading`
+### `loading`
 
 All components also have a `loading` parameter which indicates that they are currently processing some event. Setting the parameter will display the global `loading_spinner` on top of the component. To configure the loading spinner you can set the:
 
@@ -63,7 +63,7 @@ In the notebook these should be configured before loading the `pn.extension` and
 pn.pane.HTML(background='#00aa41', width=100, height=100, loading=True)
 ```
 
-#### ``style``
+### ``style``
 
 Certain components, specifically markup-related panes, expose a ``style`` parameter that allows defining CSS styles applying to the HTML container of the pane's contents, e.g. the ``Markdown`` pane:
 
@@ -72,7 +72,7 @@ Certain components, specifically markup-related panes, expose a ``style`` parame
 pn.pane.Markdown('### A serif Markdown heading', style={'font-family': "serif"})
 ```
 
-#### ``visible``
+### ``visible``
 
 All components provide a `visible` parameter which allows toggling whether the component should be visible or not. Below we display a set of components and provide some widgets to toggle the `visible` property on or off:
 
@@ -96,7 +96,7 @@ pn.Column(controls, layout)
 
 The size of components and their spacing is also controlled through a set of parameters shared by all components.
 
-#### ``margin``
+### ``margin``
 
 The ``margin`` parameter can be used to create space around an element defined as the number of pixels at the (top, right, bottom, and left). The ``margin`` can be defined in one of three ways:
 
@@ -122,7 +122,7 @@ pn.Row(
     pn.Column(pn.widgets.Button(name='Run', margin=(25, 50, 75, 100)), background='#f0f0f0'))
 ```
 
-## ``align``
+### ``align``
 
 The `align` parameter controls how components align vertically and horizontally. It supports 'start', 'center', and 'end' values and can be set for both horizontal and vertical directions at once or for each separately by passing in a tuple of the form `(horizontal, vertical)`.
 
@@ -159,11 +159,11 @@ pn.Row(
 
 Unlike other components, the size of a plot is usually determined by the underlying plotting library, so it may be necessary to ensure that you set the size and aspect when declaring the plot.
 
-### Responsive sizing
+## Responsive sizing
 
 By default, panel objects will use a fixed size if one is provided or adapt to the size of the content. However most panel objects also support reactive sizing which adjusts depending on the size of the viewport. These responsive sizing modes can be controlled using the ``sizing_mode`` parameter.
 
-#### ``sizing_mode``
+### ``sizing_mode``
 
 * **"fixed"**: Component is not responsive. It will retain its original width and height regardless of any subsequent browser window resize events.
 
@@ -216,7 +216,7 @@ pn.Column(
     height=400, width=500, background='#3f3f3f')
 ```
 
-### Spacers
+## Spacers
 
 Spacers are a very versatile component which makes it easy to put fixed or responsive spacing between objects. Like all other components spacers support both absolute and responsive sizing modes:
 

doc/user_guide/Links.md

@@ -79,7 +79,7 @@ selected = pn.pane.Markdown(object='')
 toggle = pn.widgets.ToggleGroup(options=['A', 'B'])
 ```
 
-#### Defining a callback
+### Defining a callback
 
 Next we define a callback that can handle multiple parameter changes at once and uses the ``Event``'s ``name`` to figure out how to process the event. In this case it updates either the ``selections`` or the ``selected`` pane depending on whether ToggleGroup ``options`` or ``value`` changed:
 
@@ -94,7 +94,7 @@ def callback(*events):
             selected.object = 'Selected: %s' % ','.join(event.new)
 ```
 
-#### Event objects
+### Event objects
 
 Before going any further let us discover what these ``Event`` objects are. An ``Event`` is used to signal the change in a parameter value. Event objects provide a number of useful attributes that provides additional information about the event:
 
@@ -106,7 +106,7 @@ Before going any further let us discover what these ``Event`` objects are. An ``
 * **``obj``**: The Parameterized instance that holds the parameter
 * **``cls``**: The Parameterized class that holds the parameter
 
-#### Registering a watcher
+### Registering a watcher
 
 Now that we know how to define a callback and make use of ``Event`` attributes, it is time to register the callback. The ``obj.param.watch`` method lets us supply the callback along with the parameters we want to watch. Additionally we can declare whether the events should only be triggered when the parameter value changes, or every time the parameter is set:
 
@@ -141,7 +141,7 @@ Using `set_param` allows us to batch two separate changes (the options and the v
 
 Now that the widgets are visible, you can toggle the option values and see the selected pane update in response via the callback (if Python is running).
 
-#### Unlinking
+### Unlinking
 
 If for whatever reason we want to stop watching parameter changes we can unsubscribe by passing our ``watcher`` (returned in the ``watch`` call above) to the ``unwatch`` method:
 
@@ -254,7 +254,7 @@ pn.Row(value1, operator, value2, button, result)
 
 The above examples link widgets to simple static panes, but links are probably most useful when combined with dynamic objects like plots.
 
-#### Bokeh
+### Bokeh
 
 The ``jslink`` API trivially allows us to link a parameter on a Panel widget to a Bokeh plot property. Here we create a Bokeh Figure with a simple sine curve. The ``jslink`` method allows us to pass any Bokeh model held by the Figure as the ``target``, then link the widget value to some property on it. E.g. here we link a ``FloatSlider`` value to the ``line_width`` of the ``Line`` glyph:
 
@@ -272,7 +272,7 @@ width_slider.jslink(r.glyph, value='line_width')
 pn.Column(width_slider, p)
 ```
 
-#### HoloViews
+### HoloViews
 
 Bokeh models allow us to directly access the underlying models and properties, but this access is more indirect when working with HoloViews objects. HoloViews makes various models available directly in the namespace so that they can be accessed for linking: