Skip to content

Commit

Permalink
Merge pull request #39 from Openscapes/dry-run-edits
Browse files Browse the repository at this point in the history 
Edits following dry run
  • Loading branch information
@stefaniebutland
stefaniebutland authored Jun 25, 2024
2 parents eeb02c3 + 19227ed commit bd2b12a
Show file tree
Hide file tree
Showing 8 changed files with 87 additions and 187 deletions.
4 changes: 2 additions & 2 deletions _quarto.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ website:
contents:
- href: index.qmd
text: Welcome
- href: setup-explore.qmd
text: Setup & Explore
- href: setup.qmd
text: Setup
- section: lessons/index.qmd
text: Lessons
contents:
Expand Down
Binary file added images/horst_quarto_schematic.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
23 changes: 14 additions & 9 deletions index.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,27 @@ subtitle: "Contribute to open educational resources, onboarding docs, and much m

## 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 or your colleagues use for analyses, whether or not you write code.
This book is an example of a Quarto website that is published via GitHub - these are powerful workflows to create and share your work.

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.
Quarto lets us build websites as a collection of files (`.qmd`, `.ipynb`, `.rmd` and others). Today we'll focus on `.qmd` files, which are plain-text files that work nicely with GitHub workflows.

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.
Quarto enables us to collaborate on documentation and tutorials - across Python and R languages and varied levels of coding expertise. Importantly, it lets us write and share documentation/tutorials using the same tools we teach research teams for reproducible science.

**To begin**, you should have a GitHub account with access to the 2i2c Openscapes JupyterHub.
The ability for Quarto to streamline collaboration has been so cool and important for our [NASA Openscapes](https://nasa-openscapes.github.io/) project, so this tutorial will enable you to contribute to that site as well as the [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/) (both made with Quarto+GitHub.)

## Our Plan today
![](images/horst_quarto_schematic.png){fig-alt="3 part illustration left-to-right that starts with R, Python, Julia, Observable and more pointing to Quarto and then pointing to html, pdf, and word documents" fig-align="center" width="1100"}

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/).
## Our Plan today

This is a 1.5-hr clinic that has demos and time for hands-on practice in breakout rooms.
We will learn workflows with Quarto and GitHub for contributing to open source documentation. We'll cover contributing in 2 parts:

**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 1. Quarto Workflow:** Use the 2i2c Openscapes JupyterHub as an editor: we will contribute to this Quarto site by editing a `.qmd` file 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.
**Part 2. GitHub Workflow:** Clone the repository for this site, make a branch to work in, 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.

## Prerequisites

**To begin**, you should have a GitHub account with access to the 2i2c Openscapes JupyterHub.

19 changes: 10 additions & 9 deletions lessons/demo.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,7 @@ We can all practice Markdown in this Quarto file. Make an edit, preview how it w
Only make changes to the section below under *your* name header (to prevent conflicts with other people's edits)
:::

### Stefanie

For your first edit, you could fix this tpyo and preview how it will look in the site.
## Ideas for contributions

#### **Headers**

Expand All @@ -42,21 +40,24 @@ When you **Render**, a document will be generated that includes both content and

*TODO: day before clinic, make this Python code (don't add screenshot - fewer files to for folks to get distracted with, lighter weight repo)*

```{r}
#| echo: false
```{bash}
2 * 2
```

You can add options to executable code. The `echo: false` option disables the printing of code (only output is displayed).

### Julie

## Stefanie

For your first edit, you could fix this tpyo and preview how it will look in the site.


## Julie

For your first edit, you could fix this tpyo and preview how it will look in the site.

### Andy
## Andy

For your first edit, you could fix this tpyo and preview how it will look in the site.

## Your turn!

Change or add something to this file under your Name header and save the file.
25 changes: 7 additions & 18 deletions lessons/index.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,12 @@ title: Practice

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.

## Workflow to edit a Quarto site source
<!---
TODO: some overarching statement/illustration of: ("there's a lot of jargon/concepts:)
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.
Quarto is a thing that lets you combine different file times we build to ... (preview, .qmd, and how they are built together)
GitHub is how we contribute to...
JupyterHub / terminal
Branches
--->

## Workflow to contribute via GitHub

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

## Let's try these workflows!
166 changes: 27 additions & 139 deletions lessons/part1-quarto.qmd
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,17 @@
---
title: "Part 1: Edit a Quarto site"
title: "Part 1: Quarto workflow"
---

## Preview the site (aka Quarto preview)
## Workflow to edit a Quarto website source

1. Preview the website (`quarto preview`)
2. Make changes to files
3. Save and preview how changes are automatically updated!

## Demo: Edit and preview a demo.qmd file
I will demonstrate this with the `demo.qmd` file: watch me and then you will all have a chance to do this yourself.

### Preview the website (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!

Expand All @@ -15,158 +24,37 @@ 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: add new screenshots*

![](images/jupyter-side-by-side.png){fig-align="center"}
<!---*TODO: add new screenshots* TODO only show demo.qmd example
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.
![](images/jupyter-side-by-side.png){fig-align="center"} --->

## Make changes to the site content

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
## Make changes to files (aka the website content)

**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%"}

#### 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 our changes! If it does not, you can also refresh the page manually.

### Task 1b: Create a new `.ipynb` page

Let's add a new page to our site. Instead of a `.qmd` file like the others, let's add a `.ipynb` file.

File \> New \> Notebook. Accept the default kernel by clicking Select.

*TODO: screenshot*

#### First chunk: raw yaml

By default, this Notebook will give us a first chunk that is code. Let's change it to raw so that we can write our yaml at the top.

![](images/jupyter-raw-chunk.png){fig-align="center"}

In our Raw code chunk, let's write the title of this document. We need three dashes `---` on separate lines preceding and following the `title:`, which you can name as you'd like.

``` bash
---
title: Python Example
---
```

#### Second chunk: Markdown

Let's add a new chunk that is Markdown so we can write some description of what this page will be.

Click the `+` symbol at the top of the document, and this will add a new chunk, which by default again is a Code chunk. Change it to a Markdown Chunk following the steps we did above when switching to Raw.

Here, write a little bit of text in Markdown. Since your title is effectively a level-1 header, avoid using level-1 headers in the rest of your document. Here is some example text I wrote:

``` bash
## Introduction

This example has some Python code that will be a part of our Quarto site.
```

#### Third chunk: Code

Now let's create a new chunk with the default Code setting.

Paste the following code (or write some of your own to test):

``` python
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"
import numpy as np
import matplotlib.pyplot as plt
r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
subplot_kw = {'projection': 'polar'}
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```
I will fix a small typo.

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.
### Save and preview automagically updates!

Note that the code runs as it normally would; the code options in the comments are just comments.
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.

#### Save your file
This is powerful to be able to see live changes in the preview as we edit in our `.qmd` files.

Save your document. Name it `python-yourname.ipynb`.
## Your turn

::: 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.
:::
In your breakout room:

## Preview your updates (Regroup, 10 min)
- In terminal, `cd quarto-clinic` and then `quarto preview`
- Open `demo.qmd` file
- Find the header with your name, edit in that section. Ideas at the top of the file.
- Save, `quarto preview`
- Repeat!

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`

Let's have a closer look at the `_quarto.yml` file.

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 arrangements that we see in the previewed site.

*TODO: update screenshots and dont' use line \#*

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-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"}

So, your normal workflow for creating and running code blocks in your Jupyter Notebook is the same one you'll use as Quarto displays the preview.

### Quarto render

*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 `.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.

````{=html}
<!--- ### Render whole notebook
*TODO: incorporate/ link to [Cookbook Quarto render](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/contributing/workflow.html#quarto-render)*
If you would like it to specifically execute code in a Jupyter notebook, you can do so in Terminal.
Our Terminal is still busy previewing our website, so let's open a new Terminal.
File \> New \> Terminal. Then type:
``` bash
cd quarto-website-tutorial
quarto render python-example.ipynb --execute
```
--->
````
## Regroup discussion topics

## Onward
- When adding new files, update `_quarto.yml` file as needed to have new content appear in the site's nav bar. (see https://openscapes.github.io/quarto-website-tutorial/explore.html)

Now we can move to [Part 2](part2-github.qmd) to Contribute your proposed updates using Git and GitHub.
22 changes: 21 additions & 1 deletion lessons/part2-github.qmd
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,19 @@
---
title: "Part 2: Contribute via GitHub"
title: "Part 2: GitHub workflow"
---

## Workflow to contribute via GitHub

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

## Contribute your updates using GitHub

Now that we have each saved some changes to files in our Quarto site source, liike `.qmd`, `.ipynb`, and/or `_quarto.yml`, we can contribute our updates using GitHub.
Expand Down Expand Up @@ -74,3 +86,11 @@ As the author, you can now address the reviewer's comments and then merge your P
Pair up in breakouts to make and review each other's Pull Requests

## View your updates in the live site (Regroup, 10 min)

## Regroup discussion topics

**Short message: commit the freeze folder.**

- Freeze directory contains the results of code execution.
- Commit the freeze directory after you run quarto preview.
- If there are merge conflicts when you submit to NASA Openscapes Cookbook, maintainers will help resolve them.
15 changes: 6 additions & 9 deletions setup-explore.qmd → setup.qmd
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: "Setup and Explore"
title: "Setup"
editor: visual
---

Expand All @@ -17,12 +17,6 @@ It takes a few minutes for the Hub to load. Please be patient!

While the server starts up, we’ll explore the Quarto 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. 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 looking at the website architecture and its source GitHub repository. Then we'll setup a copy for ourselves so that we can modify starting from a working example, which is a great way to learn something new.

### The website

This Quarto Clinic website has 4 things you can see on the left navbar:
Expand All @@ -34,7 +28,7 @@ This Quarto Clinic website has 4 things you can see on the left navbar:

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
### The website's source repo - is this helpful for this clinic?

Let's go to this website's GitHub repository (or "repo"). You can get there from any page in this clinic website by clicking the GitHub Octocat icon underneath the Openscapes logo in the left navbar.

Expand Down Expand Up @@ -63,6 +57,8 @@ git clone https://github.com/openscapes/quarto-clinic
cd quarto-clinic
```

### Aside: What is a branch?

### Create a new 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" on GitHub.
Expand All @@ -85,4 +81,5 @@ We'll follow the instructions in the 2021 Cloud Hackathon to [Setup your Persona

## Onward!

Now we are ready to start editing! The next chapter describes how to do this in the JupyterHub.
Since we have each set up our own GitHub clone with our unique branch of this Quarto Clinic website in the Hub, now we are ready to start editing! The next chapter describes how to do this in the JupyterHub.

0 comments on commit bd2b12a

Please sign in to comment.