Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add new user guides and remove old ones [doc-build] #340

Merged
merged 2 commits into from
Mar 29, 2019
Merged

Add new user guides and remove old ones [doc-build] #340

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
71769ab
Add new user guides and remove old ones
philippjfr Mar 29, 2019
19e2454
Removed kernel specs
philippjfr Mar 29, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions doc/user_guide/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,24 @@ User Guide
* `Introduction <Introduction.html>`_
An overview of the capabilities of Panel.

* `Overview <Overview.html>`_
A high-level overview of the user guide and key concepts in Panel.

* `Components <Components.html>`_
An introduction to the three main component types: Widgets, Panes and Panel layouts.

* `Customization <Customization.html>`_
How to customize the visual appearance, layout and size of Panel components.

* `Deploy & Export <Deploy_and_Export.html>`_
Introduction to displaying, exporting and deploying panel apps

* `Interact <Interact.html>`_
Quickly making a panel using `interact()`.

* `Panes <Panes.html>`_
Adding visual components to your panel with panes.

* `Widgets <Widgets.html>`_
Declaring and working with Panel widgets.

* `Layouts <Layouts.html>`_
Declaring and working with Panel layouts.

* `Parameters <Param.html>`_
Using Param to express panels in a self-contained class.

Expand All @@ -43,12 +46,12 @@ Supplementary guides
:maxdepth: 2

Introduction <Introduction>
Overview <Overview>
Components <Components>
Customization <Customization>
Deploy & Export <Deploy_and_Export>
Interact <Interact>
Panes <Panes>
Widgets <Widgets>
Layouts <Layouts>
Interact <Interact>
Parameters <Param>
Linking <Links>
Pipelines <Pipelines>
Expand Down
147 changes: 106 additions & 41 deletions examples/user_guide/Components.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,18 +179,22 @@
"\n",
"## Panel layouts\n",
"\n",
"The third type of component is are the Panel layout objects which allow arranging widget and pane objects into everything from a simple app to a complex dashboard. There are four main types of Layout containers:\n",
"The third type of component is are the Panel layout objects which allow arranging widget and pane objects into fixed size or responsively resizing layouts to build simply apps or complex dashboard. There are four main types of ``Panel`` objects:\n",
"\n",
"* **``Row``**: A ``Row`` arranges a list of components horizontally.\n",
"* **``Column``**: A ``Column`` arranges a list of components vertically.\n",
"* **``Tabs``**: ``Tabs`` lay out components in a list of selectable tabs. \n",
"* **``GridSpec``**: A ``GridSpec`` lays out components on a grid.\n",
"\n",
"In addition to these layout containers ``Spacer`` components allow controlling the spacing between components.\n",
"In addition to these layout containers the ``Spacer`` components allow controlling the spacing between other components.\n",
"\n",
"### Row & Column\n",
"\n",
"The ``Row``, ``Column`` and ``Tabs`` layouts behave very similarly, they are list-like, which means they have many of the same methods as a simple Python list, making it easy to add, replace and remove components using ``append``, ``extend``, ``clear``, ``insert``, ``pop``, ``remove`` and ``__setitem__``."
"The ``Row``, ``Column`` and ``Tabs`` layouts behave very similarly, they are list-like, which means they have many of the same methods as a simple Python list, making it easy to add, replace and remove components interactively using ``append``, ``extend``, ``clear``, ``insert``, ``pop``, ``remove`` and ``__setitem__``. These methods making it possible to interactively configure and modify an arrangement of plots, making them an extremely powerful tool for building apps or dashboards.\n",
"\n",
"``Row`` and ``Column`` can be initialized as empty or with the objects to be displayed as arguments. If the object is not already a ``Widget``, ``Pane`` or ``Panel`` layout component the layout will internally use ``pn.panel`` function to convert the object to a displayable representation.\n",
"\n",
"To start with, we will declare a ``Column`` and populate it with a title and a widget:"
]
},
{
Expand All @@ -199,27 +203,73 @@
"metadata": {},
"outputs": [],
"source": [
"column = pn.Column()\n",
"\n",
"# Add an item\n",
"column.append('# A title')\n",
"\n",
"# Add multiple items\n",
"column.extend([pn.widgets.FloatSlider(), pn.widgets.TextInput()])\n",
"\n",
"# Replace the third item\n",
"column[2] = pn.widgets.Button(name='Click here')\n",
"column = pn.Column('# A title', pn.widgets.FloatSlider())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next we add another bit of markdown:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"column.append('* Item 1\\n* Item 2')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Then we add a few more widgets:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"column.extend([pn.widgets.TextInput(), pn.widgets.Checkbox(name='Tick this!')])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"and finally we change our mind and replace the ``Checkbox`` with a button:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"column[3] = pn.widgets.Button(name='Click here')\n",
"\n",
"column"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The ability to add, remove and replace items opens up the possibility to building rich and responsive GUIs with the ease of manipulating a list."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Tabs\n",
"\n",
"The ``Tabs`` object shares all the same methods however, when adding or replacing items it is also possible to pass a tuple providing a custom title:"
"The ``Tabs`` layout allows is displaying multiple objects as individually toggleable tabs. Just like ``Column`` and ``Row`` it acts like a list, however, when adding or replacing items it is also possible to pass a tuple providing a custom title:"
]
},
{
Expand All @@ -230,11 +280,11 @@
"source": [
"from bokeh.plotting import figure\n",
"\n",
"tabs = pn.Tabs()\n",
"\n",
"p1 = figure(width=300, height=300)\n",
"p1.line([1, 2, 3], [1, 2, 3])\n",
"\n",
"tabs = pn.Tabs(p1)\n",
"\n",
"# Add a tab\n",
"tabs.append(('Slider', pn.widgets.FloatSlider()))\n",
"\n",
Expand All @@ -244,9 +294,6 @@
" ('Color', pn.widgets.ColorPicker())\n",
"])\n",
"\n",
"# Replace a tab\n",
"tabs[0] = ('Line Plot', p1)\n",
"\n",
"tabs"
]
},
Expand Down Expand Up @@ -285,11 +332,14 @@
"gspec = pn.GridSpec(sizing_mode='stretch_both', max_height=800)\n",
"\n",
"gspec[0, :3] = pn.pane.HTML(\"A\", background='#FF0000')\n",
"gspec[1:3, 0] = pn.pane.HTML(\"B\", background='#00FF00')\n",
"gspec[1:3, 0] = pn.pane.HTML(\"B\", background='#0000FF')\n",
"gspec[1:3, 1:3] = fig\n",
"gspec[3:5, 0] = hv.Curve([1, 2, 3])\n",
"gspec[3:5, 1] = 'https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png'\n",
"gspec[4:5, 2] = pn.Column(pn.widgets.FloatSlider(), pn.widgets.ColorPicker(), pn.widgets.Toggle(name='Toggle me'))\n",
"gspec[4:5, 2] = pn.Column(\n",
" pn.widgets.FloatSlider(),\n",
" pn.widgets.ColorPicker(),\n",
" pn.widgets.Toggle(name='Toggle Me!'))\n",
"\n",
"gspec"
]
Expand All @@ -298,23 +348,51 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"When assigning to a grid cell that is already occupied ``GridSpec`` will generate a helpful warning which highlights which objects are overlapping an where:"
"When assigning to a grid cell that is already occupied ``GridSpec`` will generate a helpful warning which highlights which objects are overlapping and where:"
]
},
{
"cell_type": "code",
"execution_count": null,
"cell_type": "markdown",
"metadata": {},
"outputs": [],
"source": [
"gspec[0:3, :2] = 'Some text'"
"```python\n",
"gspec[0:3, :2] = 'Some text'\n",
"```\n",
"\n",
"```bash\n",
"---------------------------------------------------------------------------\n",
"IndexError Traceback (most recent call last)\n",
"<ipython-input-3-b07710585904> in <module>\n",
"----> 1 gspec[0:3, :2] = 'Some text'\n",
"\n",
"~/development/panel/panel/layout.py in __setitem__(self, index, obj)\n",
" 640 'The following shows a view of the grid '\n",
" 641 '(empty: 0, occupied: 1, overlapping: 2):\\n\\n'+\n",
"--> 642 str(grid.astype('uint8')))\n",
" \n",
"IndexError: Specified region overlaps with the following existing object(s) in the grid:\n",
"\n",
" (0, 0): HTML(str, background='#FF0000', sizing_mode='stretch_both')\n",
"\n",
" (1, 0): HTML(str, background='#00FF00', sizing_mode='stretch_both')\n",
"\n",
" (1, 1): Str(ndarray, sizing_mode='stretch_both')\n",
"\n",
"The following shows a view of the grid (empty: 0, occupied: 1, overlapping: 2):\n",
"\n",
"[[2 2 1]\n",
" [2 2 1]\n",
" [2 2 1]\n",
" [1 1 0]\n",
" [1 1 1]]\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In addition to assignment we can also slice and index the ``GridSpec`` to access an individual objects or a subregion of the grid, e.g. here we will access the last row and the last two columns:"
"In addition to assignment, we can also slice and index the ``GridSpec`` to access an individual object or a subregion of the grid, e.g. here we will access the last row and everything except the first column:"
]
},
{
Expand All @@ -328,22 +406,9 @@
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.6.8"
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
Expand Down
Loading