Adds docstrings to layouts (#3417)

* add docstrings

* update docstring

Co-authored-by: Marc Skov Madsen <masma@orsted.dk>

examples/reference/layouts/GridBox.ipynb

@@ -14,7 +14,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The ``GridBox`` is a list-like layout (unlike ``GridSpec``) that wraps objects into a grid according to the specified ``nrows`` and ``ncols`` paraameters. It has a list-like API with methods to ``append``, ``extend``, ``clear``, ``insert``, ``pop``, ``remove`` and ``__setitem__``, which make it possible to interactively update and modify the layout.\n",
+    "The ``GridBox`` is a list-like layout (unlike ``GridSpec``) that wraps objects into a grid according to the specified ``nrows`` and ``ncols`` parameters. It has a list-like API with methods to ``append``, ``extend``, ``clear``, ``insert``, ``pop``, ``remove`` and ``__setitem__``, which make it possible to interactively update and modify the layout.\n",
     "\n",
     "#### Parameters:\n",
     "\n",

panel/layout/__init__.py

@@ -1,3 +1,33 @@
+"""
+Layout
+======
+
+Layouts can layout your python objects and panel components.
+
+Most layouts behave as the Python containers you already know. For example
+`Column` and `Row` behaves as lists. I.e. they have a list-like API with
+methods to `append`, `extend`, `clear`, `insert`, `pop`, `remove` and
+`__setitem__`, which make it possible to interactively update and modify them.
+
+Check out the Panel gallery of layouts
+https://panel.holoviz.org/reference/index.html#layouts for inspiration.
+
+How to use layouts in 2 simple steps
+------------------------------------
+
+1. Define your Python objects
+
+>>> some_python_object = ...
+>>> some_widget = pn.widgets...
+>>> some_pane = pn.pane...
+
+2. Define your layouts
+
+>>> pn.Column(some_python_object, some_widget, some_pane)
+
+For more detail see the Getting Started Guide
+https://panel.holoviz.org/getting_started/index.html
+"""
 from .accordion import Accordion # noqa
 from .base import Column, ListLike, ListPanel, Panel, Row, WidgetBox # noqa
 from .card import Card # noqa

panel/layout/accordion.py

@@ -7,6 +7,23 @@
 
 
 class Accordion(NamedListPanel):
+    """
+    The `Accordion` layout is a type of `Card` layout that allows switching
+    between multiple objects by clicking on the corresponding card header.
+    
+    The labels for each card will default to the `name` parameter of the card’s
+    contents, but may also be defined explicitly as part of a tuple.
+    
+    Like `Column` and `Row`, `Accordion` has a list-like API that allows
+    interactively updating and modifying the cards using the methods `append`,
+    `extend`, `clear`, `insert`, `pop`, `remove` and `__setitem__`.
+
+    Reference: https://panel.holoviz.org/reference/layouts/Accordion.html
+
+    :Example:
+
+    >>> pn.Accordion(some_pane_with_a_name, ("Plot", some_plot))
+    """
 
     active_header_background = param.String(default='#ccc', doc="""
         Color for currently active headers.""")

panel/layout/base.py

@@ -680,7 +680,18 @@ def _cleanup(self, root):
 
 class Row(ListPanel):
     """
-    Horizontal layout of Viewables.
+    The `Row` layout allows arranging multiple panel objects in a horizontal
+    container.
+    
+    It has a list-like API with methods to `append`, `extend`, `clear`,
+    `insert`, `pop`, `remove` and `__setitem__`, which makes it possible to
+    interactively update and modify the layout.
+    
+    Reference: https://panel.holoviz.org/reference/layouts/Row.html
+
+    :Example:
+
+    >>> pn.Row(some_widget, some_pane, some_python_object)
     """
 
     col_sizing = param.Parameter()
@@ -692,7 +703,18 @@ class Row(ListPanel):
 
 class Column(ListPanel):
     """
-    Vertical layout of Viewables.
+    The `Column` layout allows arranging multiple panel objects in a vertical
+    container.
+    
+    It has a list-like API with methods to `append`, `extend`, `clear`,
+    `insert`, `pop`, `remove` and `__setitem__`, which makes it possible to
+    interactively update and modify the layout.
+    
+    Reference: https://panel.holoviz.org/reference/layouts/Column.html
+
+    :Example:
+
+    >>> pn.Column(some_widget, some_pane, some_python_object)
     """
 
     row_sizing = param.Parameter()
@@ -704,7 +726,21 @@ class Column(ListPanel):
 
 class WidgetBox(ListPanel):
     """
-    Vertical layout of widgets.
+    The `WidgetBox` layout allows arranging multiple panel objects in a
+    vertical (or horizontal) container.
+
+    It is largely identical to the `Column` layout, but has some default
+    styling that makes widgets be clearly grouped together visually.
+    
+    It has a list-like API with methods to `append`, `extend`, `clear`,
+    `insert`, `pop`, `remove` and `__setitem__`, which make it possible to
+    interactively update and modify the layout.
+    
+    Reference: https://panel.holoviz.org/reference/layouts/WidgetBox.html
+
+    :Example:
+
+    >>> pn.WidgetBox(some_widget, another_widget)
     """
 
     css_classes = param.List(default=['panel-widget-box'], doc="""

panel/layout/card.py

@@ -6,8 +6,17 @@
 
 class Card(Column):
     """
-    A Card layout allows arranging multiple panel objects in a
+    A `Card` layout allows arranging multiple panel objects in a
     collapsible, vertical container with a header bar.
+    
+    Reference: https://panel.holoviz.org/reference/layouts/Card.html
+
+    :Example:
+
+    >>> pn.Card(
+    ...     some_widget, some_pane, some_python_object,
+    ...     title='Card', background='WhiteSmoke'
+    ... )
     """
 
     active_header_background = param.String(doc="""

panel/layout/flex.py

@@ -7,6 +7,24 @@
 
 
 class FlexBox(ListLike, ReactiveHTML):
+    """
+    The `FlexBox` is a list-like layout (unlike `GridSpec`) that wraps objects
+    into a CSS flex container. 
+    
+    It has a list-like API with methods to `append`, `extend`, `clear`,
+    `insert`, `pop`, `remove` and `__setitem__`, which makes it possible to
+    interactively update and modify the layout. It exposes all the CSS options
+    for controlling the behavior and layout of the flex box.
+    
+    Reference: https://panel.holoviz.org/reference/layouts/FlexBox.html
+
+    :Example:
+
+    >>> pn.FlexBox(
+    ...    some_python_object, another_python_object, ..., 
+    ...    the_last_python_object
+    ... )
+    """
 
     align_content = param.Selector(default='flex-start', objects=[
         'normal', 'flex-start', 'flex-end', 'center', 'space-between',

panel/layout/grid.py

@@ -18,8 +18,21 @@
 
 class GridBox(ListPanel):
     """
-    List-like Grid which wraps depending on the specified number of
-    rows or columns.
+    The `GridBox` is a list-like layout (unlike `GridSpec`) that wraps objects
+    into a grid according to the specified `nrows` and `ncols` parameters.
+    
+    It has a list-like API with methods to `append`, `extend`, `clear`,
+    `insert`, `pop`, `remove` and `__setitem__`, which makes it possible to
+    interactively update and modify the layout. 
+    
+    Reference: https://panel.holoviz.org/reference/layouts/GridBox.html
+
+    :Example:
+    
+    >>> pn.GridBox(
+    ...    python_object_1, python_object_2, ..., 
+    ...    python_object_24, ncols=6
+    ... )
     """
 
     nrows = param.Integer(default=None, bounds=(0, None), doc="""

panel/layout/gridstack.py

@@ -10,8 +10,25 @@
 
 class GridStack(ReactiveHTML, GridSpec):
     """
-    The GridStack layout builds on the GridSpec component and
-    gridstack.js to allow resizing and dragging items in the grid.
+    The `GridStack` layout allows arranging multiple Panel objects in a grid
+    using a simple API to assign objects to individual grid cells or to a grid
+    span.
+    
+    Other layout containers function like lists, but a `GridSpec` has an API
+    similar to a 2D array, making it possible to use 2D assignment to populate,
+    index, and slice the grid.
+    
+    Reference: https://panel.holoviz.org/reference/layouts/GridStack.html
+
+    :Example:
+    
+    >>> pn.extension('gridstack')
+    >>> gstack = GridStack(sizing_mode='stretch_both')
+    >>> gstack[ : , 0: 3] = pn.Spacer(background='red',    margin=0)
+    >>> gstack[0:2, 3: 9] = pn.Spacer(background='green',  margin=0)
+    >>> gstack[2:4, 6:12] = pn.Spacer(background='orange', margin=0)
+    >>> gstack[4:6, 3:12] = pn.Spacer(background='blue',   margin=0)
+    >>> gstack[0:2, 9:12] = pn.Spacer(background='purple', margin=0)
     """
 
     allow_resize = param.Boolean(default=True, doc="""

panel/layout/spacer.py

@@ -10,7 +10,23 @@
 
 
 class Spacer(Reactive):
-    """Empty object used to control formatting (using positive or negative space)"""
+    """
+    The `Spacer` layout is 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.
+    
+    Reference: https://panel.holoviz.org/user_guide/Customization.html#spacers
+
+    :Example:
+    
+    >>> pn.Row(
+    ...    1, pn.Spacer(width=200),
+    ...    2, pn.Spacer(width=100),
+    ...    3
+    ... )
+    """
 
     _bokeh_model = BkSpacer
 
@@ -25,22 +41,62 @@ def _get_model(self, doc, root=None, parent=None, comm=None):
 
 class VSpacer(Spacer):
     """
-    Spacer which automatically fills all available vertical space.
+    The `VSpacer` layout provides responsive vertical spacing. 
+    
+    Using this component we can space objects equidistantly in a layout and
+    allow the empty space to shrink when the browser is resized.
+    
+    Reference: https://panel.holoviz.org/user_guide/Customization.html#spacers
+
+    :Example:
+    
+    >>> pn.Column(
+    ...     pn.layout.VSpacer(), 'Item 1',
+    ...     pn.layout.VSpacer(), 'Item 2',
+    ...     pn.layout.VSpacer()
+    ... )
     """
 
     sizing_mode = param.Parameter(default='stretch_height', readonly=True)
 
 
 class HSpacer(Spacer):
     """
-    Spacer which automatically fills all available horizontal space.
+    The `HSpacer` layout provides responsive vertical spacing. 
+    
+    Using this component we can space objects equidistantly in a layout and
+    allow the empty space to shrink when the browser is resized.
+    
+    Reference: https://panel.holoviz.org/user_guide/Customization.html#spacers
+
+    :Example:
+    
+    >>> pn.Row(
+    ...     pn.layout.HSpacer(), 'Item 1',
+    ...     pn.layout.HSpacer(), 'Item 2',
+    ...     pn.layout.HSpacer()
+    ... )
     """
 
     sizing_mode = param.Parameter(default='stretch_width', readonly=True)
 
 
 class Divider(Reactive):
-    """A Divider line"""
+    """
+    A `Divider` draws a horizontal rule (a `<hr>` tag in HTML) to separate
+    multiple components in a layout. It automatically spans the full width of
+    the container.
+    
+    Reference: https://panel.holoviz.org/reference/layouts/Divider.html
+
+    :Example:
+    
+    >>> pn.Column(
+    ...     '# Lorem Ipsum',
+    ...     pn.layout.Divider(),
+    ...     'A very long text... '
+    >>> )
+    """
 
     width_policy = param.ObjectSelector(default="fit", readonly=True)
 

panel/layout/tabs.py

@@ -16,7 +16,21 @@
 
 class Tabs(NamedListPanel):
     """
-    Panel of Viewables to be displayed in separate tabs.
+    The `Tabs` layout allows switching between multiple objects by clicking
+    on the corresponding tab header.
+    
+    Tab labels may be defined explicitly as part of a tuple or will be
+    inferred from the `name` parameter of the tab’s contents.
+    
+    Like `Column` and `Row`, `Tabs` has a list-like API with methods to
+    `append`, `extend`, `clear`, `insert`, `pop`, `remove` and `__setitem__`,
+    which make it possible to interactively update and modify the tabs.
+    
+    Reference: https://panel.holoviz.org/reference/layouts/Tabs.html
+
+    :Example:
+    
+    >>> pn.Tabs(('Scatter', plot1), some_pane_with_a_name)
     """
 
     closable = param.Boolean(default=False, doc="""