Add tutorial section for documentation

doc/_static/css/custom.css

@@ -77,3 +77,7 @@ button.copybtn:hover {
 .o-tooltip--left:after {
   background: none;
 }
+
+video {
+  max-width: 100%;
+}

doc/tutorials/development.md → doc/explanation/develop_seamlessly.md

@@ -1,19 +1,18 @@
-# Effective Development
+# Develop seamlessly Across Environments
 
-:::{note} Tutorial 4. **Efficient Development**
-:icon: false
+We believe you and your team develop in a wide range of development environments. For example in a notebook for data exploration, model training, research or study. For example in an editor for other use cases. That means you and your team will be utilizing a combination of development environments like Jupyter Notebook, Jupyter Lab, Jupyter Hub, Binder, Google Colab, Spyder, VS Code, PyCharm etc..
 
- It's also important for you to be able to use a coding environment you are comfortable with. To this end, Panel offers very good support for Jupyter Notebooks (Classic and JupyterLab) and editors like Visual Studio Code, which are the two environments we will cover in this guide.
-
-:::
+Therefore **we want to enable you and your team to develop seamlessly with Panel across a wide range of development environments**.
 
 ## Notebook
 
+We love notebooks.
+
 ### Notebook friendly
 
-Jupyter notebooks have been supported in Panel since day 1 and more generally since the inception of the HoloViz project. Notebooks are environments that allow to iterate quickly, running some code and observing instantaneously its output. Notebooks also happen to be a valid deployment option:
+Jupyter notebooks have been supported in Panel since day 1 and more generally since the inception of the [HoloViz](https://holoviz.org) project. Notebooks are environments that allow to iterate quickly, running some code and observing instantaneously its output. Notebooks also happen to be a valid deployment option:
 
-- you can actually develop apps that are meant to live only in a notebook, that you will share as a file with your colleagues and friends. Panel allows you to make your notebooks more user friendly, like IPywidgets does.
+- you can actually develop apps that are meant to live only in a notebook, that you will share as a file with your colleagues and friends. Panel allows you to make your notebooks more user friendly, like [IPywidgets](https://ipywidgets.readthedocs.io/en/stable/) does.
 - you can serve a notebook with `panel serve file.ipynb`, Panel will parse your notebook to collect all of its code and run it as if it were a Python script.
 
 Jupyter notebooks aren't the only flavor of notebooks available, Panel also supports Visual Studio Code and Google Colab notebooks, and probably works fine on other platforms. For Visual Studio Code notebooks, you will need to install the `jupyter_bokeh` package in your environment.
@@ -28,7 +27,7 @@ import panel as pn
 pn.extension()
 ```
 
-The extension ensures that all required Javascript and CSS resources are added to your notebook environment. If you are going to be using any custom extensions, such as [Vega](../reference/panes/Vega.md) or [Tabulator](../reference/widgets/Tabulator.md) you must ensure that you initialize these as well.
+The extension ensures that the [`pyviz_comms`](https://github.com/holoviz/pyviz_comms) and all required Javascript and CSS resources are added to your notebook environment. If you are going to be using any custom extensions, such as [Vega](../reference/panes/Vega.md) or [Tabulator](../reference/widgets/Tabulator.md) you must ensure that you initialize these as well.
 
 ```{pyodide}
 pn.extension('vega', 'tabulator')
@@ -69,7 +68,7 @@ pn.Row(w, pn.bind(compute, w))
 
 ### Render templates
 
-You have been told in the previous guide to avoid rendering Panel templates in a notebook. That's however not a dead end! There are two approaches you can leverage to display an app that is wrapped in a template while working from a notebook, in addition to just being able to serve the notebook with `panel serve notebook.ipynb`.
+You have been told in the Panel tutorial to avoid rendering Panel templates in a notebook. That's however not a dead end! There are two approaches you can leverage to display an app that is wrapped in a template while working from a notebook, in addition to just being able to serve the notebook with `panel serve notebook.ipynb`.
 
 Templates, as any other Panel visual components, are equipped with the `.show()` method that when called starts a Bokeh server, serves your app and opens it in a new tab. While this approach doesn't allow you to iterate super quickly, it's a simple way to check what your app looks like when served.
 
@@ -116,11 +115,13 @@ This is what you should be able to see after a little while. Now tick `Render on
 
 ![alt text](../_static/images/jlabpreview.png)
 
-## Visual Studio Code
+## Editor
+
+Editors like VS Code and PyCharm have quickly become some of the most popular Python coding environment.
 
-Visual Studio Code (VS Code) has quickly become one of the most popular Python coding environment. In this section you will see how you can to set yourself a nice developer experience with VS Code when developing a Panel app.
+### Serve apps with autoreload
 
-### Setup and autoreload
+To enable a quick feedback loop while developing, we support serving your apps with autoreload.
 
 Save the content of the next cell in a file named `app.py`.
 
@@ -153,35 +154,15 @@ The `--show` flag will open a browser tab with the live app and the `--autoreloa
 
 ![VSCode Preview](../_static/images/vscode_preview.png)
 
-### Debugging
-
-While you can debug your app using the often blamed but never outperformed `print`, or by manually adding breakpoints with `breakpoint()`, the VS Code integrated debugger offers a more user friendly experience.
-
-To configure the integrated debugger for Panel, you will need to add a debugging configuration like the following.
-
-```json
-// .vscode/launch.json
-{
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "name": "panel serve",
-            "type": "python",
-            "request": "launch",
-            "program": "-m",
-            "args": [
-                "panel",
-                "serve",
-                "${relativeFile}",
-                "--show"
-            ],
-            "console": "integratedTerminal",
-            "justMyCode": true
-        }
-    ]
-}
-```
+## Resources
+
+### Tutorials
+
+- [Develop in an Editor (Basic)](../tutorials/basic/develop_editor.md)
+- [Develop in an Editor (Intermediate)](../tutorials/intermediate/develop_editor.md)¨
+- [Develop in a Notebook (Basic)](../tutorials/basic/develop_notebook.md)
 
-With this configuration in place, launching the debugger will serve the file you are working on with Panel, open a new browser tab pointing at the served app. Interact then with your app to hit one of the breakpoints you set up in VS Code.
+### How-to
 
-![VSCode Debugging](../static/images/vscode_debug.png)
+- [Configure VS Code](../how_to/editor/vscode_configure.md)
+- [Write apps in Markdown](../how_to/editor/markdown.md)

doc/explanation/index.md

@@ -4,6 +4,20 @@ The explanation section aims to clarify, deepen, and broaden the understanding o
 
 Beyond the [Getting Started > Core Concepts](../getting_started/core_concepts.md), which new users must complete before working with Panel, this explanation section is intended to help practitioners form and strengthen a conceptual web that facilitates new and advanced usage directions.
 
+## Develop
+
+::::{grid} 1 2 2 3
+:gutter: 1 1 1 2
+
+:::{grid-item-card} {octicon}`code;2.5em;sd-mr-1 sd-animate-grow50` Develop Seamlessly
+:link: api/index
+:link-type: doc
+
+Learn how we enable you and your team to work seamlessly with Panel across a wide range of development environments
+:::
+
+::::
+
 ## APIs
 
 ::::{grid} 1 2 2 3

doc/getting_started/index.md

@@ -2,7 +2,7 @@
 
 Welcome to Panel!
 
-The getting started guide will get you set up with Panel and provide a basic overview of the features and strengths of Panel.
+The getting started guide will get you set up with Panel and provide you with a basic introduction to the features and strengths of Panel.
 
 ---
 

doc/how_to/authentication/basic.md

@@ -59,7 +59,7 @@ panel serve app.py --basic-auth credentials.json --cookie-secret my_super_safe_c
 
 The basic auth provider will now check the provided credentials against the credentials declared in this file.
 
-:::note
+:::{admonition} Note
 When serving an application dynamically using `pn.serve` you can also provide a dictionary of usernames and passwords via the `basic_auth` keyword argument.
 :::
 

doc/how_to/editor/index.md

@@ -5,20 +5,6 @@ One of the main design goals for Panel was to make it seamless to work across de
 ::::{grid} 1 2 2 3
 :gutter: 1 1 1 2
 
-:::{grid-item-card} {octicon}`code-square;2.5em;sd-mr-1 sd-animate-grow50` Develop apps in an editor
-:link: editor
-:link-type: doc
-
-How to rapidly develop a Panel application in your favorite IDE or editor.
-:::
-
-:::{grid-item-card} {octicon}`bug;2.5em;sd-mr-1 sd-animate-grow50` Debug apps in an editor
-:link: editor_debug
-:link-type: doc
-
-How to debug a Panel application in your favorite IDE or editor.
-:::
-
 :::{grid-item-card} {octicon}`gear;2.5em;sd-mr-1 sd-animate-grow50` Configure VS Code
 :link: vscode_configure
 :link-type: doc
@@ -40,6 +26,6 @@ How to write Panel applications inside Markdown files.
 :hidden:
 :maxdepth: 2
 
-editor
+vscode_configure
 markdown
 ```

doc/how_to/editor/vscode_configure.md

@@ -4,7 +4,7 @@ This guide addresses how to configure VS Code for an efficient Panel development
 
 We assume you have
 
-- a basic understanding of [developing Panel apps in an editor](editor.md) and [working with Python in VS Code](https://code.visualstudio.com/docs/python/python-tutorial).
+- a basic understanding of [working with Python in VS Code](https://code.visualstudio.com/docs/python/python-tutorial).
 - installed the VS Code [Python extension](https://github.com/Microsoft/vscode-python)
 
 ---

doc/how_to/index.md

@@ -3,7 +3,7 @@
 The Panel How-to guides provide step by step recipes for solving essential problems and tasks that arise during your work. They assume that you've completed the Getting Started material and therefore already have some knowledge of how Panel works. There is no order to the guides, other than any potential prerequisites listed at the top of a page. Jump to the topic that is relevant to you now.
 
 
-## Prepare to develop
+## Develop Efficiently
 
 ::::{grid} 1 2 2 3
 :gutter: 1 1 1 2

doc/how_to/server/commandline.md

@@ -1,4 +1,4 @@
-# Launching a server on the commandline
+# Launch a server on the commandline
 
 Once the app is ready for deployment it can be served using the Bokeh server.  For a detailed breakdown of the design and functionality of Bokeh server, see the [Bokeh documentation](https://bokeh.pydata.org/en/latest/docs/user_guide/server.html). The most important thing to know is that Panel (and Bokeh) provide a CLI command to serve a Python script, app directory, or Jupyter notebook containing a Bokeh or Panel app. To launch a server using the CLI, simply run:
 
@@ -20,7 +20,7 @@ We recommend installing `watchfiles`, which will provide a significantly better
 
 The ``panel serve`` command has the following options:
 
-``` console
+```bash
 positional arguments:
   DIRECTORY-OR-SCRIPT   The app directories or scripts to serve (serve empty document if not specified)
 

doc/how_to/streamlit_migration/get_started.md

@@ -1,6 +1,6 @@
-# Get Started migrating from Streamlit to Panel
+# Serve Apps
 
-This guide addresses the basics of migrating from Streamlit to Panel.
+This guide will show you how-to migrate and serve a *Hello World* application.
 
 ---
 

doc/how_to/streamlit_migration/index.md

@@ -14,14 +14,14 @@ These guides can also be used as:
 ::::{grid} 1 2 2 3
 :gutter: 1 1 1 2
 
-:::{grid-item-card} {octicon}`rocket;2.5em;sd-mr-1 sd-animate-grow50` Get Started
+:::{grid-item-card} {octicon}`rocket;2.5em;sd-mr-1 sd-animate-grow50` Serve Apps
 :link: get_started
 :link-type: doc
 
-How to convert a Hello World application from Streamlit to Panel
+How to convert a *Hello World* application from Streamlit to Panel and serve it
 :::
 
-:::{grid-item-card} {octicon}`device-desktop;2.5em;sd-mr-1 sd-animate-grow50` Display Content
+:::{grid-item-card} {octicon}`device-desktop;2.5em;sd-mr-1 sd-animate-grow50` Display Objects
 :link: panes
 :link-type: doc
 

doc/how_to/streamlit_migration/interactivity.md

@@ -93,7 +93,7 @@ data = np.random.normal(1, 1, size=100)
 bins_input = pn.widgets.IntSlider(value=20, start=10, end=30, step=1, name="Bins")
 bplot = pn.bind(plot, data=data, bins=bins_input)
 
-pn.Column(bins, bplot).servable()
+pn.Column(bins_input, bplot).servable()
 ```
 
 ![Panel Basic Interactivity Example](https://assets.holoviz.org/panel/gifs/panel_interactivity_example.gif)

doc/how_to/streamlit_migration/layouts.md

@@ -1,6 +1,6 @@
-# Organize Components with Layouts
+# Layout Objects
 
-*Layouts* helps you organize your Panel *components*, i.e. *panes*, *widgets* and *layouts*.
+*Layouts* helps you organize your *objects* including Panel *components*.
 
 Panel provides layouts similar to the ones you know from Streamlit and many unique ones too.
 

doc/how_to/streamlit_migration/panes.md

@@ -1,4 +1,4 @@
-# Displaying Content with Panes
+# Display Objects with Panes
 
 In Panel the objects that can display your Python objects are called *panes*. With Panels *panes* you will be able to:
 

doc/tutorials/basic/align.md

@@ -0,0 +1,11 @@
+# Align
+
+COMING UP: `align`
+
+ChatGPT suggests this is *intermediate* level stuff.
+
+## References
+
+### How-to
+
+- [Align Components](../../how_to/layout/align.html)