Merge pull request #29 from Openscapes/jun18

Jun18 edits after cowork w Andy

lessons/demo.qmd

@@ -4,27 +4,22 @@ title: "`demo.qmd` Quarto Practice"
 
 Quarto enables you to weave together content and executable code into a finished document.
 
-This `demo.qmd` file has Markdown-formatted text, examples for adding 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. Headers are powerful in Quarto because they let you organize on the side of the page. They let you share a specific section of a page by copying the URL
--   hyperlink something (cite the Cookbook and hyperlink it). Hyperlinking is done like this; lets you cite and give credit
--   inspect this image with alt-txt
--   Python code. manage echo, run
+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.
 
-Stef will demo then it's your turn.
+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
 
-*TODO: Edit down to what we need, duplicated under each name header*
+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)
 :::
 
-Now let's practice Markdown in this Quarto file and commit an edit to this file. Open the `demo.qmd`
-
-Make an edit, preview, edit etc
-
 ### Stefanie
 
 Your first edit? Fix this tpyo.
@@ -39,7 +34,11 @@ We can make hyperlinks using the `[]()` pattern: you name the hyperlink in `[]`
 
 #### **Images**
 
-We can include an image with the same `[]()` pattern, by adding a preceding exclamation point: `![]()`. The `[]` contain the caption and `()` contain the path to the image file. Other attributes like image size, alt text, and a hyperlink, are also set in this example:
+We can include an image with the same `[]()` pattern, by adding a preceding exclamation point: `![]()`. The `[]` contain the caption (optional) and `()` contain the path to the image file.
+
+![The Openscapes logo](/images/openscapes_hex.png){width="150"}
+
+Additional attributes like image size, alt text, and linking the image to a URL, are set inside `{}` in this example:
 
 [![The Openscapes logo](/images/openscapes_hex.png){fig-alt="Openscapes logo. A hexagonal shape with orange border, yellow background, the word openscapes in orange above a cartoon evoking a landscape of data plots" width="150"}](https://openscapes.org/)
 

lessons/index.qmd

@@ -17,7 +17,7 @@ How do you work in Quarto? You can use whichever tool you're comfortable with (J
 
 ## Authoring
 
-*TODO: change "authoring" heading? Move to "Edit a Quarto site"*
+*TODO: Move to "Edit a Quarto site"*
 
 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.
 

lessons/newfile.qmd

@@ -0,0 +1,5 @@
+---
+title: "newfile"
+---
+
+This is a file we'll use to show how to make its content appear in our site, by editing the `_quarto.yml` file

lessons/part1-quarto.qmd

@@ -19,27 +19,31 @@ 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 add new screenshots*
+*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*
+*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
 
-## Choose Task 1a or 1b to do in breakouts
+First we'll demonstrate, then you can choose either Task 1a or 1b to try in a breakout room.
 
 ### Task 1a: Edit and preview a demo.qmd file
 
-Open [`lessons/demo.qmd`](demo.qmd) file. The suggestions / how-to for this are in the 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.
 
-*TODO: finesse opening demo.qmd; Markdown only shows when going to Raw then Markdown (this belongs in the demo file itself I think)*
+![Open .qmd file with the Editor](images/jupyterhub-openwith-editor.png){fig-align="left" width="50%"}
 
-*TODO: screenshot*
+*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, etc. When we save changes, our preview window will refresh automatically! If it does not, you can also refresh the page manually. The refreshed previewed site will now display your changes!
+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.
 
 ### Task 1b: Create a new `.ipynb` page
 
@@ -99,13 +103,17 @@ ax.grid(True)
 plt.show()
 ```
 
-Now, go ahead and execute this code chunk like you normally would, by clicking the cursor in a code block and clicking the sideways "play" triangle to run the selected cells (and advance to the next cell). This code produces a plot.
+Now, execute this code chunk as you normally would, by clicking the cursor in a code block and clicking the sideways "play" triangle to run the selected cells (and advance to the next cell). This code produces a plot.
 
 Note that the code runs as it normally would; the code options in the comments are just comments.
 
 #### Save your file
 
-Save your document - I'll call mine `python-example.ipynb` in the main repository.
+Save your document. Name it `python-yourname.ipynb`.
+
+::: callout-important
+In this Clinic, you must give unique filenames to any new files you create. This will help avoid conflicts that will arise from several people creating files called `example.ipynb` and trying to display them in the site.
+:::
 
 ## Preview your updates (Regroup, 10 min)
 
@@ -115,13 +123,13 @@ Save your document - I'll call mine `python-example.ipynb` in the main repositor
 
 *TODO: don't call it Basic Workflows below, where to put it new files?*
 
-Now we'll add `python-example.ipynb` or `your_demo_file.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".
+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".
 
 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.
 
-TODO: update screenshots and dont' use line \#
+*TODO: update screenshots and dont' use line \#*
 
 Add `- python-example.ipynb` to line 46, making sure that your indentation aligns with the other pages.
 

lessons/part2-github.qmd

@@ -6,15 +6,15 @@ title: "Part 2: Contribute via GitHub"
 
 *TODO: use text and some screenshot styles from 2021 Cloud Hackathon [Tracking changes section](https://nasa-openscapes.github.io/2021-Cloud-Hackathon/tutorials/00_Setup.html#step-5.-tracking-changes-optional). Those screenshots are so clean and text so clear.*
 
-*TODO: do we add this text? "We have set it up so that any modifications (commits) will automatically be republished via GitHub Actions."*
+*TODO: add this text somewhere? "We have set it up so that any modifications (commits) will automatically be republished via GitHub Actions."*
 
 GitHub commit, push, (move to GitHub.com….) pull request, review PRs, merge
 
 1.  Good commit messages
 2.  Push to GitHub then move to GitHub.com, screenshot yellow banner to compare and make a pull request
 3.  Not finished proposing your updates? Can make Draft PR at the start so folks can see your thinking. Set Ready for Review when ready. Request specific reviewer(s). 
 4.  Condense/ adapt [Review a pull request](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/contributing/workflow.html#review-a-pull-request) from Cookbook; note using “suggesting” and commenting, “Start your Review” instead of adding single comments (fewer notifications)
-5.  **Demo**: have someone commit and push, PR, tag Stef as reviewer. Screenshare the above steps to review. That person screenshares to commit suggested edits, merge their PR.
+5.  **Demo**: Andy commit and push, make a pull request, tag Stef as reviewer. Screenshare the above steps to review. Andy screenshares to commit suggested edits, merge his pull request.
 6.  **Task**: people pair up to review each other’s PRs.
 
 ### Diff, Stage, Commit, and Push your edits to GitHub
@@ -29,8 +29,12 @@ In the Git tab "stage" your saved changes.
 
 Commit your edits with a good commit message and push your edits.
 
+*TODO: What makes a good commit message (from GitHub Clinic)*
+
 ![Commit and Push](images/jupyterhub-git-commit-push.png){fig-align="left" width="50%"}
 
+On your first commit, you will be prompted to add your Git credentials. When you are working on a project over time, you can have them stored, following instructions in [Configure Git (git config)](https://nasa-openscapes.github.io/2021-Cloud-Hackathon/tutorials/00_Setup.html#step-5.1.-configure-git-git-config) from the 2021 Cloud Hackathon.
+
 In the Hub, in our own branch of the Quarto Clinic repo, we have made one or more edits to the Clinic files, committed those updates, and pushed those commit(s) to GitHub. How do our suggested contributions get incorporated into the main Quarto Clinic repo and website?
 
 ## Make a Pull Request
@@ -39,7 +43,7 @@ After pushing your edits, go to <https://github.com/Openscapes/quarto-clinic/> a
 
 ![](images/github-yellow-pr-banner.png){fig-align="left" width="90%"}
 
-Not finished proposing your updates? Can make Draft PR at the start so folks can see your thinking. Set Ready for Review when ready and request specific reviewer(s).
+Not finished proposing your updates? You can set your Pull Request as a Draft at the start so folks can see your thinking. Set Ready for Review when ready and request a reviewer(s); preferable someone who knows about what you are contributing.
 
 ## Review a pull request
 
@@ -74,7 +78,7 @@ Now, switch to the 2i2c Hub to view the Cookbook preview as it would appear if t
     -   Go to the Main branch and pull so that we have the most recent changes from remote.
     -   `git checkout` to the branch that has the PR: reorg_how_to_guides (note, this PR has been merged and the branch deleted so you won't see this one; apply this example to your own)
     -   `quarto preview` - this will build the book with Andy's suggested edits. *TODO: Is this preview link still an issue?* <!-- -   At the end of the preview log, it says "Browse at 
-                                            <!--     https://openscapes.2i2c.cloud..." The Browse URL actually --> <!--     points to the production Hub!! We need it to point to --> <!--     staging since that's where we're working, so we use the URL --> <!--     staging.openscapes.2i2c.cloud.... (See minute 10:06 in the --> <!--     [video](https://youtu.be/2_F5Kr6gM1I?t=606).) -->
+                                                <!--     https://openscapes.2i2c.cloud..." The Browse URL actually --> <!--     points to the production Hub!! We need it to point to --> <!--     staging since that's where we're working, so we use the URL --> <!--     staging.openscapes.2i2c.cloud.... (See minute 10:06 in the --> <!--     [video](https://youtu.be/2_F5Kr6gM1I?t=606).) -->
 
 We can now view the changes in the built Quarto book and concurrently look at the files changed in GitHub.