Tutorial: Intro to Shiny for Python Express

_quarto.yml

@@ -19,6 +19,8 @@ project:
     - api/core
     - api/testing
     - templates
+    - get-started
+    - tutorials
   resources:
     - /pypi/**
     - /robots.txt
@@ -73,7 +75,9 @@ website:
     logo-alt: The logo for Shiny for Python
     search: true
     left:
-      - text: "Learn Shiny"
+      - text: "Get Started"
+        file: get-started/welcome.qmd
+      - text: "Concepts"
         file: docs/overview.qmd
       - text: "Components"
         menu:
@@ -86,13 +90,6 @@ website:
           - 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: "Playground"
@@ -227,7 +224,32 @@ website:
             - text: "Controlling for Page Size"
               href: "/layouts/arrange/index.html#controlling-for-page-width-and-height"
 
-    - id: docs
+    - id: get-started
+      style: "floating"
+      collapse-level: 1
+      align: left
+      contents:
+        - text: "<span class='emoji-icon'>👋</span>  Welcome"
+          href: "/get-started/welcome.qmd"
+        - text: "<span class='emoji-icon'>📦</span>  Installation"
+          href: "/get-started/install.qmd"
+        - text: "<span class='emoji-icon'>🏃‍♂️</span>  Create and Run"
+          href: "/get-started/create-run.qmd"
+        - text: "<span class='emoji-icon'>🐛</span>  Debug"
+          href: "/get-started/debug.qmd"
+        - section: "<span class='emoji-icon'>🚀</span>  Deploy"
+          contents:
+            - text: "Overview"
+              href: get-started/deploy.qmd
+            - get-started/deploy-cloud.qmd
+            - get-started/deploy-on-prem.qmd
+            - get-started/shinylive.qmd
+        - section: "Tutorials"
+          contents:
+            - text: "Get Started with Shiny Express"
+              href: tutorials/intro-express/1-welcome.qmd
+
+    - id: concepts
       style: "floating"
       collapse-level: 2
       align: left
@@ -236,10 +258,6 @@ website:
           contents:
             - docs/overview.qmd
             - docs/user-interfaces.qmd
-        - section: "<span class='emoji-icon'>💻</span>  __Workflow__"
-          contents:
-            - docs/install-create-run.qmd
-            - docs/debug.qmd
         - section: "<span class='emoji-icon'>🎨</span>  __User interfaces__"
           contents:
             - docs/ui-overview.qmd
@@ -278,6 +296,21 @@ website:
           contents:
             - docs/nonblocking.qmd
             - docs/routing.qmd
+
+    - id: tutorial-express-intro
+      style: "docked"
+      align: left
+      contents:
+        - section: "Learn Shiny Express"
+          contents:
+            - tutorials/intro-express/1-welcome.qmd
+            - tutorials/intro-express/2-ui.qmd
+            - tutorials/intro-express/3-inputs.qmd
+            - tutorials/intro-express/4-external.qmd
+            - tutorials/intro-express/5-outputs.qmd
+            - tutorials/intro-express/6-reactivity.qmd
+            - tutorials/intro-express/7-publish.qmd
+            - tutorials/intro-express/8-next.qmd
     # TODO: if the sidebar only has 1 entry, then it displays for the entire site...
     # added entry below to prevent this.
     - id: deploy

docs/_metadata.yml

@@ -1 +1 @@
-sidebar: get-started
+sidebar: concepts

get-started/_metadata.yml

@@ -0,0 +1 @@
+sidebar: get-started

get-started/create-run.qmd

@@ -0,0 +1,80 @@
+---
+title: "Create and Run"
+---
+
+When you [install shiny](get-started/install.qmd), you will have access to the `shiny` command line interface (CLI).
+You can use this interface to help you create and run your Shiny applications.
+
+## Create a Shiny application
+
+The best way to create a new Shiny app is with the `shiny create` command line interface.
+This command asks you a series of questions about what kind of app you want to create,
+and then provides all the boilerplate code you need to get started with a working app.
+
+```bash
+shiny create
+```
+
+![Running the shiny create command from a terminal](/docs/assets/shiny-create.mp4){class="img-shadow"}
+
+::: callout-tip
+### Copy/paste examples
+
+If you find an example on this site that you want to run or edit locally,
+you can use the following command to get a basic app template,
+then copy and paste the code from the example into the template.
+
+```bash
+shiny create --template basic-app -m express
+```
+:::
+
+
+## Run your Shiny application
+
+Shiny apps can be launched from Positron, VS Code, or the command line via `shiny run`.
+
+::: {.callout-tip}
+#### Name your app `app.py`
+
+We recommend naming your shiny application `app.py`.
+This is the default file that `shiny run` will look for, so you can run the application in the terminal without any additional parameters.
+
+If you need a more unique name, we recommend beginning the file with `app`, so the shiny extension can still run with a [play button click](install.qmd#positron).
+:::
+
+### Positron and VS Code
+
+The best way to run (and develop) Shiny apps is in [Positron][positron] or [Visual Studio Code][vscode] with the [Shiny extension][vscode-shiny].
+When a Shiny `app.py` file is being edited, the default behavior of the Run button (circled in red in the screenshot below) becomes "Run Shiny App".
+
+![Visual Studio Code running with the Shiny extension](assets/positron-run.png)
+
+This launches a Python process in a dedicated terminal instance, and a captive web browser.
+This lets you test your app without leaving your editor, and whenever you make changes to your app's source, the preview will update. To preview your app in a full browser, click the icon to the right of the URL bar to launch the app in an external browser.
+
+Next to the Run button is a dropdown menu that lets you "Debug Shiny App". This launches the app in debug mode, which lets you set breakpoints and step through your code.
+See the [debugging](debug.qmd) section for more information.
+
+### Command line
+
+To run a Shiny app from the command line, use the `shiny run` command.
+This command takes a single argument, the path to the app's entry point.
+For example, if your app's entry point is `app.py` in the directory `./app_dir`, you can run it like this:
+
+```bash
+shiny run --reload --launch-browser app_dir/app.py
+```
+
+This should start your app and also automatically launch a web browser.
+
+The `--reload` flag means that file changes in the current directory tree will cause the Python process to restart and the browser to reload.
+Update and save changes to `app.py` and then wait a moment for the changes to appear in the browser.
+
+With these two `shiny` commands, you now have a project that you can run in your terminal.
+You can use any text editor or Python IDE to write Shiny apps, but we've taken special care to ensure a smooth workflow for [Positron][positron] and [Visual Studio Code][vscode].
+
+[positron]: https://positron.posit.co/
+[vscode]: https://code.visualstudio.com/
+[vscode-shiny]: https://marketplace.visualstudio.com/items?itemName=posit.shiny
+[vscode-python]: https://marketplace.visualstudio.com/items?itemName=ms-python.python

docs/debug.qmd → get-started/debug.qmd

@@ -57,11 +57,9 @@ The error displayed in the app is only the final part of the stack trace, but th
 When Shiny apps are deployed, error messages are sanitized to the eliminate the possibility of leaking sensitive information. To unsanitize error messages, you'll need to set `sanitize_errors=True` in the `App` constructor (of a [Shiny core app](express-vs-core.qmd)).
 :::
 
-
-
 ## Debugging
 
-### VS Code debugger
+### Positron and VS Code debugger
 
 The [VS Code debugger](https://code.visualstudio.com/docs/editor/debugging) is a powerful tool for debugging Python code.