Reorganize Menus to create Getting Started and Concepts pages #250
Conversation
chendaniely
changed the title
chendaniely
force-pushed
the
getting_started_concepts
branch
from
f5a32ff to
a7d37b8
Compare
_quarto.yml
Outdated
| - get-started/overview.qmd | ||
| - get-started/user-interfaces.qmd | ||
| - get-started/install-create-run.qmd | ||
| - get-started/debug.qmd | ||
| - section: "Deploy" | ||
| contents: | ||
| - docs/overview.qmd | ||
| - docs/user-interfaces.qmd | ||
| - section: "Workflow" | ||
| - 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: | ||
| - docs/install-create-run.qmd | ||
| - docs/debug.qmd | ||
| - text: "Get Started with Shiny Express" | ||
| href: tutorials/intro-express/1-welcome.qmd |
There was a problem hiding this comment.
I like that we have all of these pieces together in one place. I think now it's worth going through these to make sure that they all make sense together. Now that they're here are they well organized, do the sections work well together, etc?
When I compare this page with pydantic's Get Started, ours still feels disorganized.
| 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. |
There was a problem hiding this comment.
I like this style (semantic breaks rather than sentence breaks), but in practice I've found it easier to run these files through the Quarto visual editor to get the canonical pandoc formatting with sentence breaks. That ends up being a good middle ground and I like having auto-formatters be the arbiters of style.
|
|
||
| ## 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 | ||
| ``` |
There was a problem hiding this comment.
These make me nervous, in particular because they're completely untested and not something we, as a team, use. If there's a strong guarantee that these will always work, I'd be okay with leaving them in the docs, but if these approaches break or change in the future there's a very small chance that we'd notice and/or update them.
There was a problem hiding this comment.
I'm less attached to the mamba section. The mamba-only users will know how to modify from the conda install. I do feel we should keep the conda section because of how python data science is taught.
These were some example project installation:
- Stan: https://mc-stan.org/install/
- Scikit learn: https://scikit-learn.org/stable/install.html
This is the current py-shiny conda feedstock: https://github.com/conda-forge/py-shiny-feedstock
I have seen a few projects also put in uv install instructions. Since that is a tool the shiny team uses, would that be worth putting in? I've stumbled across projects that have a uv copy+paste installer
There was a problem hiding this comment.
followup: I'm removing this section so we can move all installation and setup steps to the dedicated installation page
| :::::: | ||
|
|
||
|
|
||
| We will be using [Positron](https://positron.posit.co/) in our tutorials, |
There was a problem hiding this comment.
I think it'd be reasonable to start with the IDE choice and then move on to installation, in particular so that you don't have to repeat installation instructions twice
There was a problem hiding this comment.
followup: I'm removing this section so we can move all installation and setup steps to the dedicated installation page
| 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. |
There was a problem hiding this comment.
This also feels like something that could appear in the intro before installation. This is Step 0 stuff (what we're going to do and which editor you should open), and Step 1 can be installation.
| 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. |
There was a problem hiding this comment.
This could also be something that comes earlier in the tutorial
| * 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. |
There was a problem hiding this comment.
This feels like a mix of concerns. The top-level bullets can come early to signal that we'll be talking about inputs/outputs/layouts. The second-level bullets should come later after project set-up and running the app locally when people are ready to start reading the code line-by-line.
There was a problem hiding this comment.
i moved around the text in this section. my goal here is to have them:
- see the 3 parts of an application (a place holder for each individual lesson later)
- see the example application running and reacting to the slider
- point out where each of the 3 parts of the application are in the application code
The second-level bullets should come later after project set-up and running the app locally when people are ready to start reading the code line-by-line.
I don't want to totally gloss over the code that is being displayed, otherwise we would only show the application on its own with #| components: [viewer] (which could be a separate discussion).
I think it's good to bring up the same concepts and ideas multiple times throughout the lessons.
There was a problem hiding this comment.
I'll have to see how this shakes out, but my feeling reading these bullets is that it's better done in two passes: read the top level bullets and then follow up with the second level bullets.
I guess also stylistically I'm not a fan of reading much content inside bullet lists. My personal preference would be to work very hard to keep all lists to a single level of 1-5 points, unless there's a structural hierarchy that only comes through when you see the information presented as a list. I don't think the bullet points are required here.
| 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 |
There was a problem hiding this comment.
I think it'd be interesting to work with images in the margins for these kinds of adjacent images. This would be one reason to move to the docked sidebar style for the tutorials.
| In addition to the play button in Positron, you can manually run your application from | ||
| the command line. |
There was a problem hiding this comment.
I like this order! How to run with the extension, then how to run from the cli. Great! 👏
| shiny run my_app.py | ||
| ``` | ||
|
|
||
| ::: {.callout-note} |
There was a problem hiding this comment.
I generally prefer that we give callouts informative titles, it makes them easier to read in the prose and helps them stand out from each other.
| 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 |
There was a problem hiding this comment.
I think you should include --reload when you show the first shiny run command
…tion page instead
Co-authored-by: Garrick Aden-Buie <[email protected]>
Co-authored-by: Garrick Aden-Buie <[email protected]>
Co-authored-by: Garrick Aden-Buie <[email protected]>
…erminal run example
chendaniely
force-pushed
the
getting_started_concepts
branch
from
d630045 to
0d8bdbc
Compare
|
The margin image may need to either change or we not use the margin image. it ends up really small when set as a margin image. I worry that if we make the image only the play button, there may not be enough UI context for the user to know where to click. 
|
I agree but I think there could be a middle ground where you show mostly just the editor. We can also the lightbox feature so users can click on the image to get an expanded view. I'm not ready to give up on margin images yet. |
|
|
Also, let's make the first priority getting the "Get Started" content into a good place now that we have it co-located (i.e. "Install, create, run" becoming "Installation", "Running a Shiny App" and "Create"). That way we can merge those changes even if we're still working on the tutorial. |
* get started and concept changes from #250 4751da3 * fix / remove title case from welcome page * fix nav (rm top deploy and concepts workflow), fix run title * tutorials don't exist in this PR * remove the docs/shinylive pages and images (moved to get-started) * re-direct+re-name learn shiny to get started * replace screenshot of template dashboard with actual dashboard * make dashboard example 90% width, fix trailing :::: link to create and run * remove *.quarto_ipynb * add reactivity example and clean up template example * fix link to shiny create video in get started to link to docs * add emojis to get started to match concepts * round of edits + the component buttons aren't right * make the buttons a bit smaller (still not flowing correctly) * match colors to top menu, leave a reference to posit blue * don't use bullets with emojis, just list with the emojis * fix font awesome, and buttons not flowing correctly * fix typo * remove copy+pasted repeted text * write a short blurb about the shiny example * 200px button size a bit too big. moving to 150px * split up welcome, now with more links * add a point to open source * fix same typo in #268 * chore: Use quarto v1.7.23 * feat: initial shiny app preview * feat: cards design for gallery links * chore(welcome): Tweak CTA section * fix gallery image link and remove anchor * chore: remove component section, plus more edits * rename: what_is_shiny -> what-is-shiny * chore(what-is-shiny): style link buttons, use bsicons, small edits * fix(css): Fix source code blocks in tab content * fix(css): Fix margins on code blocks in tabs only when direct children * chore: simplify gallery highlight listing template * Update get-started/install.qmd Co-authored-by: Garrick Aden-Buie <[email protected]> * Update get-started/install.qmd Co-authored-by: Garrick Aden-Buie <[email protected]> * Update get-started/create-run.qmd Co-authored-by: Garrick Aden-Buie <[email protected]> * Update get-started/create-run.qmd Co-authored-by: Garrick Aden-Buie <[email protected]> * Update get-started/create-run.qmd Co-authored-by: Garrick Aden-Buie <[email protected]> * Update get-started/create-run.qmd Co-authored-by: Garrick Aden-Buie <[email protected]> * Update get-started/create-run.qmd Co-authored-by: Garrick Aden-Buie <[email protected]> * edits to what is shiny * some copy edits and changes * move around text in extensibility * fix css on mobile * delete ipynb file * add posit connect cloud help in debug * add and update links * feat: home page links, text color, etc. * theming link to built-in theming link * alt text for code, with image update, code, and settings for reproducibility * Update get-started/what-is-shiny.qmd Co-authored-by: Garrick Aden-Buie <[email protected]> * Update get-started/what-is-shiny.qmd Co-authored-by: Garrick Aden-Buie <[email protected]> * Update get-started/install.qmd Co-authored-by: Garrick Aden-Buie <[email protected]> * copy edit what is shiny page * what is shiny copy edit and links * update shiny create video * add fixed.py to error app examples * debug with positron and vscode debugger and images * link for positon and vs code * add hover overlay to code and app for gallery * add wording about production-ready * add missing linebreak * update install instructions to include uv * fix links to components page where components not loading * add code comment to copy + paste solution * fix grammar * turn off repo actions for index and what is shiny page * revert get-started index gallery to ec5d46f * point to template page whenever possible * fix link similar to #282 * tweak(gallery-cards): Adjust alignment and links * feat: editable code block Co-authored-by: Daniel Chen <[email protected]> * chore: use assets/code-welcome.py as source of truth for app code * chore: adjust selection color in code block * update why shiny bullets * chore(why-shiny): Formatting and add link * chore: add aliases for moved/renamed files * clean up linking styles * chore(what-is-shiny): Edit and improve Extensibility section * chore: tweak wording --------- Co-authored-by: Daniel Chen <[email protected]> Co-authored-by: Garrick Aden-Buie <[email protected]>
Goal: find a home for content.
Rename the current "getting started" section to "concepts" and create a new get starting landing page.
Also puts in the first shiny for python with express syntax tutorial