Merge pull request #35 from Openscapes/stef-jun23

June 23 -24 work

_quarto.yml

@@ -39,12 +39,9 @@ website:
       - section: lessons/index.qmd
         text: Lessons
         contents: 
-          - href: lessons/part1-quarto.qmd
-            text: Edit a Quarto site
-#          - href: lessons/demo.qmd
- #           text: demo.qmd practice file
-          - href: lessons/part2-github.qmd
-            text: Contribute via GitHub
+          - lessons/part1-quarto.qmd
+          - lessons/demo.qmd
+          - lessons/part2-github.qmd
       - href: next-steps.qmd
         text: Next Steps
 

index.qmd

@@ -1,39 +1,26 @@
 ---
-title: "Contributing to Quarto websites and books"
-subtitle: "Share open-source tutorials, onboarding docs, and much more"
+title: "Quarto + GitHub Clinic"
+subtitle: "Contribute to open educational resources, onboarding docs, and much more"
 ---
 
 ## Welcome
 
-It's possible to create beautiful documentation to share online with [Quarto](https://quarto.org) that auto-updates with [GitHub](http://github.com). This Clinic is an example of a Quarto website --- a really powerful way to create and share your work. You can communicate about science using the same reproducible workflow you and/or your colleagues use for analyses, whether or not you write code.
+It's possible to create beautiful documentation to share online with [Quarto](https://quarto.org) that auto-updates with [GitHub](http://github.com). This Clinic is an example of a Quarto website --- a really powerful way to create and share your work. You can communicate about science using the same reproducible workflow you or your colleagues use for analyses, whether or not you write code.
+
+Quarto is an open-source scientific and technical publishing system. You can weave together narrative text and code to produce elegantly formatted output as documents, web pages, blog posts, books, presentations, and more.
 
 The ability for Quarto to streamline collaboration has been so cool and important for our [NASA Openscapes](https://nasa-openscapes.github.io/) project. Quarto is a common place for us to collaborate - across Python and R languages and varied levels of coding expertise, and accessibility and inclusion are centered in the Quarto design.
 
 **To begin**, you should have a GitHub account with access to the 2i2c Openscapes JupyterHub.
 
 ## Our Plan today
 
-We will learn workflows with Quarto and GitHub for contributing to open source documentation - like the [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/). 
+We will learn workflows with Quarto and GitHub for contributing to open source documentation - like the [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/).
 
 This is a 1.5-hr clinic that has demos and time for hands-on practice in breakout rooms.
 
 **Part 1. Quarto Workflow:** Use the 2i2c Openscapes JupyterHub to explore this clinic website and its source repository on GitHub, practice contributing to this site by editing a Quarto file or adding a new Jupyter Notebook and previewing the changes.
 
 **Part 2. GitHub Workflow:** Clone the repository for this site, make a branch to work in, edit, commit and push your edits to GitHub, make a pull request, review and merge a pull request, and communicate what you’re doing at each step.
 
-This requires some setup. We'll do this first, and discuss more as we go. 
-
-<!--- TOCUT or move
-
-## What is Quarto?
-
-Quarto helps you have your ideas and your code in one place, and present it in a beautiful way.
-
-> Quarto is an open-source scientific and technical publishing system built on Pandoc. You can weave together narrative text and code to produce elegantly formatted output as documents, web pages, blog posts, books, presentations, and more.
-
-Quarto can be used to create dynamic content with Python, R, Julia, and Observable through your favorite IDE like JupyterHub or RStudio. Creating and editing websites with Quarto can be done without knowing R, Python or HTML, CSS, etc, however, Quarto integrates with these tools so you can make your websites as complex and beautiful as you like as you see examples and reuse and remix from others in the open science community.
-
-[Quarto.org](https://quarto.org) is the go-to place for full documentation and more tutorials!
-
---->
-
+This requires some setup. We'll do this first, and discuss more as we go.

lessons/demo.qmd

@@ -1,28 +1,22 @@
 ---
-title: "`demo.qmd` Quarto Practice"
+title: "`.qmd` file for practice"
 ---
 
-Quarto enables you to weave together content and executable code into a finished document.
+This `demo.qmd` file has [Markdown](https://quarto.org/docs/authoring/markdown-basics.html)-formatted text, examples for adding headers, hyperlinks, and inserting images with alt-text, and a Python code chunk.
 
-This `demo.qmd` file has Markdown-formatted text, examples for adding headers, hyperlinks, and inserting images with alt-text, and a Python code chunk.
+-   Headers are powerful in Quarto because they let you organize on the side of the page. In a Quarto site, headers let you share a specific section of a page by clicking on a header and copying the URL.
+-   Hyperlinking lets us cite our sources and inspirations and give credit.
+-   Python code in a `.qmd` file will be executed automatically.
 
-Headers are powerful in Quarto because they let you organize on the side of the page. In a Quarto site, headers let you share a specific section of a page by clicking on a header and copying the URL.
-
-Hyperlinking lets us cite our sources and inspirations and give credit.
-
-Python code in a `.qmd` file will be executed automatically. *TODO: draft manage echo, run*
-
-## Task 1a: Edit a `.qmd` page
-
-We can all practice Markdown in this Quarto file. Make an edit, preview how it will look in the site (quarto preview), edit, repeat.
+We can all practice Markdown in this Quarto file. Make an edit, preview how it will look in the site (`quarto preview`), edit, repeat.
 
 ::: callout-note
-Only make changes to the section under your name header (to prevent conflicts at a later stage)
+Only make changes to the section below under *your* name header (to prevent conflicts with other people's edits)
 :::
 
 ### Stefanie
 
-Your first edit? Fix this tpyo.
+For your first edit, you could fix this tpyo and preview how it will look in the site.
 
 #### **Headers**
 
@@ -57,13 +51,11 @@ You can add options to executable code. The `echo: false` option disables the pr
 
 ### Julie
 
-Fix this tpyo.
-
-*TODO: copy activities text under each participant heading when it's settled*
+For your first edit, you could fix this tpyo and preview how it will look in the site.
 
 ### Andy
 
-Fix this tpyo.
+For your first edit, you could fix this tpyo and preview how it will look in the site.
 
 ## Your turn!
 

lessons/index.qmd

@@ -2,36 +2,25 @@
 title: Practice
 ---
 
-*TODO: Drastically reduce this page's text. Get to the doing. This index page should say, hey here's 2 things we'll practice - Edit a Quarto site, and Contribute via GitHub. Here's the Basic Workflow*
+In this section we'll practice two workflows: [Part 1: Edit a Quarto site](part1-quarto.qmd), and [Part 2: Contribute via GitHub](part2-github.qmd). We include a basic workflow for each here, so you can come back to these for a reminder.
 
-## Authoring
+## Workflow to edit a Quarto site source
 
-*TODO: Move to "Edit a Quarto site"*
+1.  Preview the site
+2.  Make changes to files; supported types include `.qmd`, `.ipynb` `.md`, `.Rmd`.
+3.  Save, preview
+4.  Update `_quarto.yml` file as needed to have new content appear in the site's nav bar.
 
-As an author, you have a lot of options of how your text will be formatted, arranged, and interlinked. You will be writing in Markdown, which is a lightweight text formatting language. The Quarto documentation about authoring introduces [markdown-basics](https://quarto.org/docs/authoring/markdown-basics.html) that will get you started.
+## Workflow to contribute via GitHub
 
-Each page of our site has a similar first few lines - this YAML, like we saw in our `_quarto.yml` and it is indicated by two sets of 3 dashes `---` :
+1.  Inspect the differences your edits will introduce
+2.  "Stage" your changes
+3.  Commit your changes with a helpful "Commit message"
+4.  "Push" to GitHub
+5.  Go to the Clinic repo source on GitHub, in your browser
+6.  Make a "Pull Request" and tag a reviewer
+7.  Reviewer responds by commenting, making suggested commits, and submitting their review
+8.  Author responds to review and "merges" their Pull Request
+9.  A GitHub Action automatically publishes the updates in the live siteDiff, Stage, Commit, and Push your edits to GitHub
 
-``` bash
----
-title: My title
----
-```
-
-You're able to add more features to individual pages by including it in the YAML, which for the most part here only includes a title. See [Quarto excecution options](https://quarto.org/docs/computations/execution-options.html) for more information of what you can include in the YAML.
-
-## Update `_quarto.yml`
-
-*TODO: move this to Edit a Quarto site: Preview your updates (Regroup, 10 min)*
-
-Let's have a closer look at the `_quarto.yml` file.
-
-This type of file (`.yml` or `.yaml`) is written in YAML ("Yet Another Markup Language"). You'll be able to shift the arrangement of webpages by reordering/adding/deleting them in the `_quarto.yml` file following the patterns you see in this example.
-
-![\_quarto.yml and website side-by-side](images/quarto-yml-site-side-by-side3.png){fig-align="center" width="95%"}
-
-Notice that there are multiple ways in the `_quarto.yml` for you to include a file in your website. For example, in the above image, the "First Observations" we see in the left sidebar of the published website (right image) is represented in `_quarto.yml` (left image) over two lines, with line 36 indicating the file reference and line 37 indicating the text to show up in the left sidebar. However, "From RStudio" is only represented in one line of `_quarto.yml`, on line 43. This represents two strategies for including a file in your website. By default, the title of a specified file will show up in the website's sidebar, which is what is happening with the "From RStudio" example. If you would like more control over what is written in the sidebar vs the title of your files, then the approach we took with "First Observations" is what you'll want to do: you'll see that only "First Observations" shows up in the sidebar as we specified in `_quarto.yml`, but the page's title says "First Observations & Setup" (which in our preference was too long for the sidebar).
-
-::: callout-note
-As you modify `_quarto.yml`, the most important thing to know is that **spacing matters**. Pay attention to whether text is indented by one, two, four, or other spaces, and make sure you follow it; if your site is not looking as expected it is likely a silent error in your YAML. Some text editors like RStudio provide debugging support for YAML and are highly recommended to save you time and heartache.
-:::
+## Let's try these workflows!

lessons/part1-quarto.qmd

@@ -2,10 +2,6 @@
 title: "Part 1: Edit a Quarto site"
 ---
 
-The NASA Openscapes 2i2c JupyterHub ("the Hub") has a Python environment as well as Quarto installed. No further installations are required.
-
-*TODO: List here the things we'll do in this section*
-
 ## Preview the site (aka Quarto preview)
 
 Let's start off by previewing our quarto site locally. In Terminal, in the `quarto-clinic` folder, type `quarto preview`, which will provide a URL with a preview of our site!
@@ -19,31 +15,25 @@ quarto preview
 
 Open this URL in a browser window and arrange your Hub and website preview windows so you can see them both. I make a bit more space in Jupyter by collapsing the left file menu by clicking on the file icon at the top of the left sidebar.
 
-*TODO: note to open index.qmd to compare*
-
 *TODO: add new screenshots*
 
 ![](images/jupyter-side-by-side.png){fig-align="center"}
 
 Now that we have each set up our own GitHub clone with our unique branch of this Quarto Clinic website in the Hub, we can practice editing and rendering `.qmd` and `.ipynb` files. These are the workflows we use to contribute to the NASA Earthdata Cloud Cookbook and other Quarto websites and books.
 
-*TODO: quarto preview does X; quarto render does Y. This isn't the place for it. Once done, delete file \_render-vs-preview.qmd*
-
 ## Make changes to the site content
 
-First we'll demonstrate, then you can choose either Task 1a or 1b to try in a breakout room.
+Choose either [Task 1a: Edit and preview a demo.qmd file] or [Task 1b: Create a new `.ipynb` page] to try in a breakout room.
 
 ### Task 1a: Edit and preview a demo.qmd file
 
 **Open [`lessons/demo.qmd`](demo.qmd) file using the Editor, not as a Notebook file.** Suggestions for things to try, and how to format things are in the file.
 
 ![Open .qmd file with the Editor](images/jupyterhub-openwith-editor.png){fig-align="left" width="50%"}
 
-*TODO: screenshot of demo file in Hub Editor with typo showing?*
-
 #### Make a small change and preview it
 
-Now we'll be able to see live changes in the preview as we edit in our `.qmd` files. Let's try it: Fix the typo. When we save changes, our preview window will refresh automatically and display your changes! If it does not, you can also refresh the page manually.
+Now we'll be able to see live changes in the preview as we edit in our `.qmd` files. Let's try it: Fix the typo. When we save changes, our preview window will refresh automatically and display our changes! If it does not, you can also refresh the page manually.
 
 ### Task 1b: Create a new `.ipynb` page
 
@@ -117,27 +107,35 @@ In this Clinic, you must give unique filenames to any new files you create. This
 
 ## Preview your updates (Regroup, 10 min)
 
-**Demo**: If you created a new page, how do you get it in the book? Involves editing `_quarto.yml` to have it show up in site
+If you created a new page, how do you get it to appear in the site? This involves editing `_quarto.yml` to have it show up in site
 
 ### Update `_quarto.yml`
 
-*TODO: don't call it Basic Workflows below, where to put it new files?*
+Let's have a closer look at the `_quarto.yml` file.
 
-Now we'll add `python-example.ipynb` or `newfile.qmd` to our `_quarto.yml` file; this is where we register of all files to include in our site. Let's add it after the section called "Basic Workflows".
+This type of file is written in YAML ("Yet Another Markup Language"). You'll be able to shift the arrangement of webpages by reordering/adding/deleting them in the `_quarto.yml` file following the patterns you see in this example.
+
+![\_quarto.yml and website side-by-side](images/quarto-yml-site-side-by-side3.png){fig-align="center" width="95%"}
+
+Now we'll add `python-yourname.ipynb` or any `newfile.qmd` to our `_quarto.yml` file.
 
 Open `_quarto.yml` by clicking on it from the file directory.
 
-Scroll down to review the current contents in the `sidebar:` section. It's there we see all the file arrangement that we see in the previewed site.
+Scroll down to review the current contents in the `sidebar:` section. It's there we see all the file arrangements that we see in the previewed site.
 
 *TODO: update screenshots and dont' use line \#*
 
-Add `- python-example.ipynb` to line 46, making sure that your indentation aligns with the other pages.
+Add `- python-yourname.ipynb` below `- lessons/part1-quarto.qmd`, making sure that your indentation aligns with the other pages.
+
+::: callout-important
+As you modify `_quarto.yml`, the most important thing to know is that **spacing matters**. Pay attention to whether text is indented by one, two, four, or other spaces, and make sure you follow it; if your site is not looking as expected it is likely a silent error in your YAML.
+:::
 
 ![](images/jupyter-python-example.png){fig-align="center"}
 
 You'll see that our new page shows up in our Preview, and the code is executed since we did that in the Jupyter Notebook itself. By default, Quarto will not execute code chunks since your computations will likely become more complex and you will want to control when they are executed (or "run").
 
-Since Quarto is still previewing our website and the `python-example.ipynb`, the plot also displays in the notebook after the code is run and the file is saved, as shown below.
+Since Quarto is still previewing our website and the `python-yourname.ipynb`, the plot also displays in the notebook after the code is run and the file is saved, as shown below.
 
 ![](images/jupyter-execute-cell.png){fig-align="center"}
 
@@ -149,9 +147,10 @@ So, your normal workflow for creating and running code blocks in your Jupyter No
 
 So far we have used **Quarto preview** to view our website as we develop it. **Quarto render** will build the html elements of the website that we can see when we preview. Rendering will format the markdown text and code nicely as `.html` files for a website (or however is indicated in the `_quarto.yml`; could be `.docx` or `.pdf` files).
 
-By default, Quarto render does not execute code in a Jupyter notebook. It will never run .ipynb files unless you tell it to.
+By default, Quarto render does not execute code in a Jupyter notebook. It will never run `.ipynb` files unless you tell it to.
 
-### Render whole notebook
+````{=html}
+<!--- ### Render whole notebook
 
 *TODO: incorporate/ link to [Cookbook Quarto render](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/contributing/workflow.html#quarto-render)*
 
@@ -165,6 +164,8 @@ File \> New \> Terminal. Then type:
 cd quarto-website-tutorial
 quarto render python-example.ipynb --execute
 ```
+--->
+````
 
 ## Onward