[WIP] first draft for getting started learning stream

_quarto.yml

@@ -73,32 +73,49 @@ website:
     logo-alt: The logo for Shiny for Python
     search: true
     left:
-      - text: "Learn Shiny"
-        file: docs/overview.qmd
+      - text: "Tutorials"
+        menu:
+          - text: "Getting Started"
+            href: docs/learning_streams/getting_started/01-welcome.qmd
+          - text: "Tutorials"
+            href: docs/learning_streams/tutorials.qmd
+          - text: "Learning Hub"
+            href: docs/overview.qmd
+
       - text: "Components"
         menu:
-          - text: "Components"
-            file: components/index.qmd
+          - text: "Inputs"
+            href: components/index.qmd#inputs
+            icon: sliders
+          - text: "Outputs"
+            file: components/index.qmd#outputs
             icon: sliders
-          - text: "Layouts"
+          - text: "UI Layouts"
             file: layouts/index.qmd
             icon: layout-text-window-reverse
-          - text: "Templates"
-            file: templates/index.qmd
-            icon: code-square
+
       - text: "Deploy"
         menu:
           - text: "Overview"
             href: docs/deploy.qmd
           - docs/deploy-cloud.qmd
           - docs/deploy-on-prem.qmd
           - docs/shinylive.qmd
-      - text: "Gallery"
-        file: gallery/index.qmd
+
+      - text: "Examples"
+        menu:
+          - text: "Gallery"
+            href: gallery/index.qmd
+          - text: "Templates"
+            href: templates/index.qmd
+
+    right:
+
       - text: "Playground"
         href: https://shinylive.io/py/examples/
         target: _blank
-      - text: "Reference"
+
+      - text: "API Reference"
         menu:
           - text: "Shiny Express"
             href: api/express/index.qmd
@@ -227,6 +244,22 @@ website:
               href: "/layouts/arrange/index.html#controlling-for-page-width-and-height"
 
     - id: docs
+      style: "floating"
+      collapse-level: 2
+      align: left
+      contents:
+
+        - section: "Learn Shiny Express"
+          contents:
+            - docs/learning_streams/getting_started/01-welcome.qmd
+            - docs/learning_streams/getting_started/02-ui.qmd
+            - docs/learning_streams/getting_started/03-inputs.qmd
+            - docs/learning_streams/getting_started/04-scripts.qmd
+            - docs/learning_streams/getting_started/05-outputs.qmd
+            - docs/learning_streams/getting_started/06-reactive.qmd
+            - docs/learning_streams/getting_started/07-publish.qmd
+
+    - id: book
       style: "floating"
       collapse-level: 2
       align: left

docs/learning_streams/getting_started/01-welcome.qmd

@@ -0,0 +1,310 @@
+---
+title: Getting Started
+---
+
+Shiny for Python is a web application framework that helps tell your
+data story.
+If you've landed on this page,
+you probably have a bit of Python experience,
+worked with data,
+and now need a way to publish an interactive
+web application to help tell your data story.
+
+## Installing Shiny
+
+:::::: {.panel-tabset}
+
+## Windows
+
+::: {.panel-tabset}
+
+## pip
+
+```bash
+python -m venv shiny-env    # create virtual environment
+shiny-env\Scripts\activate  # activate environment
+pip install -U shiny        # install shiny
+```
+
+## conda
+
+```bash
+# create virtual environment and install shiny
+conda create -n shiny-env -c conda-forge shiny
+
+# activate environment
+conda activate shiny-env
+```
+
+## mamba
+
+```bash
+# create virtual environment and install shiny
+mamba create -n shiny-env -c conda-forge shiny
+
+# activate environment
+mamba activate shiny-env
+```
+
+:::
+
+## MacOS
+
+::: {.panel-tabset}
+
+## pip
+
+```bash
+python -m venv shiny-env       # create virtual environment
+source shiny-env/bin/activate  # activate environment
+pip install -U shiny           # install shiny
+```
+
+## conda
+
+```bash
+# create virtual environment and install shiny
+conda create -n shiny-env -c conda-forge shiny
+
+# activate environment
+conda activate shiny-env
+```
+
+## mamba
+
+```bash
+# create virtual environment and install shiny
+mamba create -n shiny-env -c conda-forge shiny
+
+# activate environment
+mamba activate shiny-env
+```
+:::
+
+## Linux
+
+::: {.panel-tabset}
+
+## pip
+
+```bash
+python -m venv shiny-env       # create virtual environment
+source shiny-env/bin/activate  # activate environment
+pip install -U shiny           # install shiny
+```
+
+## conda
+
+```bash
+# create virtual environment and install shiny
+conda create -n shiny-env -c conda-forge shiny
+
+# activate environment
+conda activate shiny-env
+```
+
+## mamba
+
+```bash
+# create virtual environment and install shiny
+mamba create -n shiny-env -c conda-forge shiny
+
+# activate environment
+mamba activate shiny-env
+```
+:::
+
+::::::
+
+
+We will be using [Positron](https://positron.posit.co/) in our tutorials,
+but you can also use [Visual Studio Code](https://code.visualstudio.com/).
+Whether you are using Positron, or VS Code,
+you will need to make sure you have the
+[VS Code Shiny Extension](https://marketplace.visualstudio.com/items?itemName=Posit.shiny)
+installed.
+
+If you are working with VSCode and Positron,
+make sure your current python environment has
+the `ipykernel` package installed.
+We assume you are already in the environment we set up in the previous installing shiny section.
+
+
+::: {.panel-tabset}
+
+## pip
+
+```bash
+pip install ipykernel
+```
+
+## conda
+
+```bash
+conda install -c conda-forge ipykernel
+```
+
+## mamba
+
+```bash
+mamba install -c conda-forge ipykernel
+```
+
+:::
+
+## Parts of a Shiny Application
+
+This is a 1 to 2 Hour tutorial to get you started and familiar with all the basic
+parts of creating and deploying a Shiny for Python application.
+
+Shiny express allows us to write shiny apps with a minimal amount of code.
+This lets us rapidly link interactive components with our data
+in our web application.
+
+There are 3 main parts of a shiny express application
+
+1. [input components](/components/#inputs):
+  provide user interactions that can be used as inputs in other parts of the web application.
+2. [output components](/components/#outputs):
+  results that are displayed on the web application.
+3. [layout and ui components](/layouts):
+  how and where the inputs and output of the web application are displayed.
+
+```{shinylive-python}
+#| standalone: true
+#| components: [editor, viewer]
+#| layout: vertical
+#| viewerHeight: 150
+from shiny.express import input, render, ui
+
+ui.input_slider("val", "Slider label", min=0, max=100, value=50)
+
+@render.text
+def slider_val():
+    return f"Slider value: {input.val()}"
+```
+
+This example demonstrates the basic mechanics behind Shiny apps.
+As you move the slider (an input component),
+the text (output component) will react and update to the corresponding input value.
+
+* Inputs are created via `ui.input_*()` functions.
+    * The first argument is the input's `id`, which is used to read the input's value.
+* Outputs are created by decorating a function with `@render.*`.
+    * Inside a `render` function, `input` values can be read [reactively](#reactivity).
+    * When those `input` values change, Shiny knows how to minimally re-render output.
+* Layouts are inferred automatically based on what items you place in your application.
+    * We will learn more about layouts and user interfaces in the next lesson of this tutorial.
+
+::: {.callout-note}
+## Exercise
+
+Let's make and run our first shiny for python application.
+
+1. Take the above code and save it to a file. Here we named it `app.py`
+2. Click on the play button (red circle in the image below)j
+
+You will see the terminal run the `shiny run` command for you automatically.
+The output will look something like this
+
+
+```bash
+$ python -m shiny run --port 55901 --reload --autoreload-port 55902 app-010-simple.py
+INFO:     Will watch for changes in these directories: ['~/Desktop/py-shiny-example']
+INFO:     Uvicorn running on http://127.0.0.1:55901 (Press CTRL+C to quit)
+INFO:     Started reloader process [24969] using WatchFiles
+INFO:     Started server process [24986]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     127.0.0.1:56426 - "GET /?vscodeBrowserReqId=1737097751843 HTTP/1.1" 200 OK
+```
+
+This will run the application on port `55901` and automatically reload and update
+as you make changes to the `app.py` file.
+
+1. You will see the app build in the bottom terminal and open in the viewer on the side
+2. Move the slider and see how the output reacts
+3. Congratulations, you made your first shiny for python application!
+
+![](img/010-run_app.png)
+
+::: {.callout-tip}
+## Naming your files
+
+If you start your file with the word `app`,
+the shiny for python extension will recognize
+it as an application and you will be able to see the "play" button to run your application.
+You can also name your file `app-getting_started.py`
+and you will still get the shiny extension play button.
+
+To have Shiny for Python work well with the VS Code extensions and for you to go through
+the next series of lessons.
+We recommend either one of the following file naming conventions:
+
+1. Create separate folders for each app example you will create and save separate `app.py` files in each folder
+2. Create separate `app*.py` files in the same directory (e.g., `app-01.py`, `app-02.py`)
+:::
+
+:::
+
+## Run your shiny application
+
+In addition to the play button in Positron, you can manually run your application from
+the command line.
+This is useful if you wish to specify your own port or want to rename your application
+without the `app` prefix.
+
+```bash
+shiny run my_app.py
+```
+
+::: {.callout-note}
+If you named your application `app.py` you can omit it form the command and only use `shiny run`.
+The `app.py` is the default file shiny looks for to run in the current directory.
+Otherwise, you can pass in the name of the file that you wish to run.
+The `app` prefix used in the example above is used to signal the VS Code shiny extension
+to display the run app button.
+:::
+
+:::{.callout-tip}
+## Helpful run options
+
+Some useful options you can pass the `shiny run` command are:
+
+- `--port`: pass in a custom port, e.g., `--port 8000`.
+  This will run the app on the specified port,
+  instead of a random port.
+  This makes it easier to have the same browser window open as you stop and start your application.
+- `--reload`: Enables auto-reload
+
+You can learn more about these run options on the
+[`run_app` documentation page](https://shiny.posit.co/py/api/core/run_app.html).
+:::
+
+## Shiny Express: Your first application
+
+The rest of this tutorial will work on creating this
+[Restaurant Tipping Dashboard](https://gallery.shinyapps.io/template-dashboard-tips1/).
+
+::::: {.column-screen .hero-image .pt-4 .pb-5 style="margin-top:0px;max-width:1600px;"}
+::: {.hello-output .g-col-12 .g-col-xl-12}
+<iframe
+  src="https://gallery.shinyapps.io/template-dashboard-tips1/"
+  frameborder="0"
+  width="100%"
+  class="mb-0 card hello-output-iframe"
+></iframe>
+
+<style>
+  .hello-output-iframe {
+    height: 900px;
+  }
+@media only screen and (max-width: 611px) {
+  .hello-output-iframe {
+    height: 2125px;
+  }
+}
+</style>
+:::
+
+:::::