Merge pull request #12 from Openscapes/part1

Clean Welcome Setup Explore structure, delete some unused images, edi…

_quarto.yml

@@ -34,17 +34,15 @@ website:
     contents:
       - href: index.qmd
         text: Welcome
-      - href: explore.qmd
-        text: Explore
+      - href: setup.qmd
+        text: Setup & Explore
       - section: lessons/index.qmd
         text: Lessons
         contents: 
-          - href: lessons/part1-edit-quarto-site.qmd
-            text: Edit a Quarto site 
-          - href: lessons/demo.qmd
-            text: Quarto practice file 
-          - href: lessons/part2-share-via-github.qmd
-            text: Share via GitHub
+          - href: lessons/part1-quarto.qmd
+            text: Edit a Quarto site
+          - href: lessons/part2-github.qmd
+            text: Contribute via GitHub
       - href: next-steps.qmd
         text: Next Steps
 

index.qmd

@@ -1,9 +1,10 @@
 ---
-title: "Contributing to Quarto books and websites"
+title: "Contributing to Quarto websites and books"
 subtitle: "Share open-source tutorials, onboarding docs, and much more"
 ---
+*TODO: edit Welcome page to include POP, What is Quarto. Brief. Move to Setup & Explore*
 
-## Welcome {#welcome}
+## 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 is very new and incredibly cool. This tutorial is an example of a quarto website --- it is 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.
 
@@ -15,15 +16,17 @@ Quarto helps you have your ideas and your code in one place, and present it in a
 
 **Quarto unifies and extends the RMarkdown ecosystem** - it unifies by combining the functionality of R Markdown, bookdown, distill, xaringian, etc into a single consistent system. And it extends in several ways: all features are possible beyond R too, including Python and Javascript. It also has more “guardrails”: accessibility and inclusion are centered in the design. Quarto is for people who love RMarkdown, and it's for people who have never used RMarkdown.
 
+*TODO: add Cookbook below* 
+
 The ability for Quarto to streamline collaboration has been so cool and important for our [NASA Openscapes](https://nasa-openscapes.github.io/) project. Quarto has been a common place for us to collaborate - across R and Python languages and coding expertise.
 
 ## What is this tutorial?
 
-This is a 1-hour tutorial that can be used to teach or as self-paced learning.
+This is a 1.5-hour tutorial that can be used to teach or as self-paced learning.
+
+We introduce Quarto by exploring this clinic website, and practicing the basic Quarto workflow using the 2i2c Openscapes JupyterHub for editing your website and GitHub in the browser to review proposed updates.
 
-We introduce Quarto by exploring this tutorial website, and practicing the basic Quarto workflow using different tools (GitHub browser, RStudio, and Jupyter) for editing your website.
 
-We'll start off from the browser so you don't need to install any additional software, however this approach is very limited and you will soon outgrow its capabilities. If you don't already have a workflow to edit files and sync to GitHub from your computer, I recommend RStudio. You don't need to know R to use RStudio, and it has powerful editor features that make for happy workflows.
 
 [Quarto.org](https://quarto.org) is the go-to place for full documentation and more tutorials!
 

lessons/part1-edit-quarto-site.qmd → lessons/part1-quarto.qmd

@@ -4,48 +4,7 @@ title: "Part 1: Edit a Quarto site"
 
 We will work through this Quarto Clinic site in the NASA Openscapes 2i2c JupyterHub ("the Hub"). The Hub has a python environment as well as Quarto installed. No further installations are required.
 
-TODO: move Setup to setup.qmd. Add Setup after Welcome, then do Explore while Hub is initiating. Setup includes Hub login, clone, branch. Leave Preview in Edit Quarto site = step 1.
-
-## Setup
-
-TODO: Don't call this "Setup"; too vague. Decide if this file is just "demo 1" or all the content of Part 1 - demo and practice for: clone, branch, preview, make changes, add ipynb, edit \_quarto.yml, preview, END
-
-### Log in to the Hub
-
-Go to the Hub https://openscapes.2i2c.cloud \> log in with your GitHub Account \> select the Python server.
-
-[![Login page for the NASA Openscapes 2i2c JupyterHub, "the Hub"](images/jupyterhub-2i2c-login.png)](https://openscapes.2i2c.cloud/)
-
-![Hub server options](images/jupyterhub-server-options.png)
-
-![](images/jupyterhub-loading.png)
-
-It takes a few minutes for the Hub to load. Please be patient!
-
-While the server starts up, we’ll explore the GitHub Clinic repo structure side by side with the website (go back to the [Explore](../explore.qmd) section).
-
-### Clone the Quarto Clinic repo
-
-You'll start by cloning your repository into the Hub.
-
-**Option A:** Use the Git tab to Clone repo
-
-![Clone a GitHub repository in the Hub](images/jupyterhyb-clone-repo.png)
-
-**Option B:** Do this by opening a terminal (File \> New \> Terminal). In the Terminal, `git clone` your repository and `cd` into it:
-
-``` bash
-git clone https://github.com/openscapes/quarto-clinic
-cd quarto-clinic
-```
-
-### Make a branch
-
-Working in a branch means you have your own version of the Quarto Clinic to edit and preview. Later, you might propose contributing your edits to the Main branch of the Clinic by making a "Pull Request".
-
-branch name = your name
-
-TODO screenshot and cmd line
+*TODO: List here the thinks we'll do in this section*
 
 ## Preview the site (aka Quarto preview)
 
@@ -72,14 +31,16 @@ TODO: add new screenshots
 
 Now that we have each set up our own GitHub clone of this Quarto Clinic website in the Openscapes 2i2c JupyterHub, 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.
 
-## Choose Task 1a or 1b (Activity)
+## Choose Task 1a or 1b to do in breakouts
 
-TODO: fill out Task 1a
+*TODO: fill out Task 1a*
 
-TODO: edit demo.md file to have only what we need
+*TODO: edit demo.md file to have only what we need*
 
 ### Task 1a: Edit and preview a demo.qmd file
 
+Open [demo.qmd](demo.qmd) file.
+
 1.  Edit a .qmd page (uses demo.qmd file that has markdown for text, add hyperlink, add image, run Python code)
 
     1.  Headers
@@ -98,9 +59,9 @@ TODO: edit demo.md file to have only what we need
 
         1.  manage echo, run
 
-TODO: screenshot
+*TODO: screenshot*
 
-TODO: edit the text below re: "make a small change"; fix a typo
+*TODO: edit the text below re: "make a small change"; fix a typo*
 
 #### Make a small change and preview it
 
@@ -112,7 +73,7 @@ Let's add a new page to our site. Instead of a `.qmd` file like the others, let'
 
 File \> New \> Notebook. Accept the default kernel by clicking Select.
 
-TODO: screenshot
+*TODO: screenshot*
 
 #### First chunk: raw yaml
 
@@ -174,11 +135,13 @@ Save your document - I'll call mine `python-example.ipynb` in the main repositor
 
 ## 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
+**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
 
 ### Update `_quarto.yml`
 
-Now we'll add `python-example.ipynb` 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".
+*TODO: not Basic Workflows, 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".
 
 Open `_quarto.yml` by clicking on it from the file directory.
 
@@ -200,9 +163,9 @@ So, your normal workflow for creating and running code blocks in your Jupyter No
 
 ### Quarto render
 
-TODO: clarify preview vs render text
+*TODO: clarify preview vs render text; cp some `render-vs-preview.qmd`*
 
-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 a website (or however is indicated in the `_quarto.yml`).
+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.
 
@@ -223,4 +186,8 @@ quarto render python-example.ipynb --execute
 
 ## Commit and push to GitHub
 
+*TODO: do we need to create a GitHub Action or is it already there?*
+
 Committing and pushing will make the changes you see locally live on your website (using the [GitHub Action we set up earlier](/explore.qmd#setup-github-action)).
+
+Now we can move to [Part 2](part2-share-via-github.qmd) to Contribute your updates via PR, review, etc

lessons/part2-github.qmd

@@ -0,0 +1,21 @@
+---
+title: "Part 2: Contribute via GitHub"
+---
+
+## Contribute your updates using GitHub
+
+*TODO: refine this list of steps, keep the list here, turn it into a demo with screenshots*
+
+1.  GitHub commit, push, pull request, review PRs, merge (now we’re on GitHub.com….)
+
+    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.
+
+    6.  **Task**: people pair up to review each other’s PRs.

setup.qmd

@@ -0,0 +1,84 @@
+---
+title: "Setup and Explore"
+editor: visual
+---
+
+TODO: Do Setup after Welcome, then do Explore while Hub is initiating. Setup includes Hub login, clone, branch. Preview site is step 1 in Lessons: Edit Quarto site.
+
+## Setup Part 1: Log in to the Hub
+
+Go to the Hub https://openscapes.2i2c.cloud \> log in with your GitHub Account \> select the Python server.
+
+[![Login page for the NASA Openscapes 2i2c JupyterHub, "the Hub"](images/jupyterhub-2i2c-login.png)](https://openscapes.2i2c.cloud/)
+
+![Hub server options](images/jupyterhub-server-options.png)
+
+![](images/jupyterhub-loading.png)
+
+It takes a few minutes for the Hub to load. Please be patient!
+
+While the server starts up, we’ll explore the GitHub Clinic website structure side by side with the repo.
+
+## Explore
+
+With this Clinic, we have a working example website that we will explore together. We'll learn a few rules and look for patterns to get an understanding of what things to do to help you start customizing and making it your own. And you can continue to use this website as a reference after the clinic, along with [Quarto](https://quarto.org) documentation.
+
+We'll start our exploration online looking at the website architecture and GitHub repository. Then we'll setup a copy for ourselves so that we can modify from a working example, which is a great way to learn something new. We'll set it up so that any modifications (commits) will automatically be republished via GitHub Actions.
+
+### The website itself
+
+[This Quarto Clinic website](https://openscapes.github.io/quarto-clinic/) has 4 things you can see on the left sidebar:
+
+-   Welcome
+-   Setup & Explore
+-   Lessons
+-   Next Steps
+
+Most of these are pages, but you'll see that "Lessons" has an arrow `>`; it is a folder with additional pages inside.
+
+### The website's source repo
+
+Let's go to this website's GitHub repository (also called a "repo"), <https://github.com/Openscapes/quarto-clinic>. You can also click there from any page in this tutorial website by clicking the GitHub octocat icon underneath the Openscapes logo in the left navbar (click it holding command on Mac, or control on a PC to open it in a different tab in your browser).
+
+**Have a look at the filenames.** We can recognize the names of the webpages we've seen above, and they have red arrows marking them in the image below. You'll see the "quarto-workflows" folder and the rest in this site are `.qmd` files, which are plain text Quarto files that can combine Markdown text with code. `index.qmd` is the home page. If you click inside "quarto-workflows" you'll see a mix of filetypes!
+
+*TODO: replace screenshots*
+
+![quarto-website-tutorial GitHub repository with files for webpages marked with red arrows](images/quarto-files-github.png){fig-alt="Screenshot of files on GitHub with red arrows identifying the files that we saw in the left sidebar" fig-align="center" width="80%"}
+
+**The `_site` folder** has html files with names that should be familiar: they match the `.qmd` files we were just exploring. This folder is where Quarto stores files to build the website.
+
+### `_quarto.yml` intro
+
+There is also a `_quarto.yml` file, which is the website's configuration file. It is essentially metadata for the website that includes the order that the pages/chapters will be in. This is where you update the organization of your website: which page comes before another. If we compare side-by-side, you'll see that the pages that appear on our website are listed there.
+
+![\_quarto.yml and website side-by-side](images/quarto-yml-site-side-by-side3.png){fig-align="center"}
+
+We'll learn more about how to interact with `_quarto.yml` in the [Lessons](lessons/index.qmd).
+
+## Setup Part 2: Clone the Quarto Clinic repo
+
+After our Hub server is loaded, we'll clone the Quarto Clinic repository into the Hub.
+
+**Option A:** Use the Git tab to Clone repo
+
+![Clone a GitHub repository in the Hub](images/jupyterhyb-clone-repo.png)
+
+**Option B:** Do this by opening a terminal (File \> New \> Terminal). In the Terminal, `git clone` your repository and `cd` into it:
+
+``` bash
+git clone https://github.com/openscapes/quarto-clinic
+cd quarto-clinic
+```
+
+### Make a branch
+
+Working in a branch means you have your own version of the Quarto Clinic to edit and preview. Later, we'll learn how to contribute your edits to the Main branch of the Clinic by making a "Pull Request".
+
+branch name = your name
+
+*TODO screenshot and cmd line*
+
+## Onward!
+
+Now you are ready to start editing! The next chapter describes how to do this in the JupyterHub.