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.

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

[WIP] first draft for getting started learning stream #245

Closed
wants to merge 12 commits into from
55 changes: 44 additions & 11 deletions _quarto.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
310 changes: 310 additions & 0 deletions docs/learning_streams/getting_started/01-welcome.qmd
Original file line number Diff line number Diff line change
@@ -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>
:::

:::::
Loading
Loading