diff --git a/_quarto.yml b/_quarto.yml index 4a86e5b..17240fc 100644 --- a/_quarto.yml +++ b/_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 diff --git a/_render-vs-preview.qmd b/_render-vs-preview.qmd deleted file mode 100644 index 8f5fbbf..0000000 --- a/_render-vs-preview.qmd +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Render vs. Preview ---- - -Making quarto websites involves terminology that might be unfamiliar. This is a light explainer to help you get going. - -As you work locally, you will save your files as you normally do. Saving writes your work to disk. - -## Render - -Rendering is when Quarto formats your document into something different (e.g. .html or .docx). - -## Preview - -Preview is when Quarto displays the rendered files. It's like saying "show me". - -## When do I want Render vs Preview? - -From the RStudio IDE, the "Render" button does both Render + Preview together. - -From Jupyter, you'll need to do these in two steps, render to make the formatted document, and preview to view it. - -From GitHub.com, Quarto will only be able to render when published (through a GitHub Action). This means you cannot preview before publishing online. diff --git a/index.qmd b/index.qmd index 55fa2de..f69e9d1 100644 --- a/index.qmd +++ b/index.qmd @@ -1,11 +1,13 @@ --- -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. @@ -13,7 +15,7 @@ The ability for Quarto to streamline collaboration has been so cool and importan ## 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. @@ -21,19 +23,4 @@ This is a 1.5-hr clinic that has demos and time for hands-on practice in breakou **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. - - - +This requires some setup. We'll do this first, and discuss more as we go. diff --git a/lessons/demo.qmd b/lessons/demo.qmd index 18e648b..a9707af 100644 --- a/lessons/demo.qmd +++ b/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! diff --git a/lessons/index.qmd b/lessons/index.qmd index 2324e80..42d7a8d 100644 --- a/lessons/index.qmd +++ b/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! diff --git a/lessons/newfile.qmd b/lessons/newfile.qmd deleted file mode 100644 index e3edbdc..0000000 --- a/lessons/newfile.qmd +++ /dev/null @@ -1,5 +0,0 @@ ---- -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 diff --git a/lessons/part1-quarto.qmd b/lessons/part1-quarto.qmd index e612bde..0d7cce7 100644 --- a/lessons/part1-quarto.qmd +++ b/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,19 +15,15 @@ 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 @@ -39,11 +31,9 @@ First we'll demonstrate, then you can choose either Task 1a or 1b to try in a br ![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} + +```` ## Onward diff --git a/lessons/part2-github.qmd b/lessons/part2-github.qmd index fab0862..cbc279f 100644 --- a/lessons/part2-github.qmd +++ b/lessons/part2-github.qmd @@ -4,22 +4,11 @@ title: "Part 2: Contribute via GitHub" ## Contribute your updates using 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.* +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. -*TODO: add this text somewhere? "We have set it up so that any modifications (commits) will automatically be republished via GitHub Actions."* +### Demonstration -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**: 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 - -Inspect the differences your edits will introduce +You have to deliberately tell Git/GitHub when you have work that you want to be versioned and synced. First, inspect the differences your edits will introduce. ![](images/jupyterhub-git-diff.png){fig-align="left" width="100%"} @@ -27,9 +16,7 @@ In the Git tab "stage" your saved changes. ![Stage your changes](images/jupyterhub-git-stage.png){fig-align="left" width="50%"} -Commit your edits with a good commit message and push your edits. - -*TODO: What makes a good commit message (from GitHub Clinic)* +Commit your edits with a good commit message and push your edits to GitHub. A commit message is a human-readable message, like leaving a breadcrumb trail for your future self and others. ![Commit and Push](images/jupyterhub-git-commit-push.png){fig-align="left" width="50%"} @@ -37,29 +24,19 @@ On your first commit, you will be prompted to add your Git credentials. When you 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 +### Make a Pull Request -After pushing your edits, go to and you will see a yellow banner inviting you to make a pull request to add your edits to the Clinic repo. +After pushing your edits, go to and you will see a yellow banner inviting you to make a Pull Request to add your edits to the Clinic repo. ![](images/github-yellow-pr-banner.png){fig-align="left" width="90%"} -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 - -*TODO: Adapt [Reviewing a pull request](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/contributing/workflow.html#review-a-pull-request) (in Cookbook). Copied; Will edit to condense, using a Stef + Andy PR & Review of edits to this clinic.* - -Any pull request (PR) must be reviewed before it can be merged into the Cookbook. If you know someone who is familiar with the content you're proposing to add, request their review. +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). For the NASA Earthdata Cloud Cookbook, any Pull Request must be reviewed before it can be merged. If you know someone who is familiar with the content you're proposing to add, request their review. -The following notes are adapted from a coworking session in which Amy Steiker and Julie Lowndes reviewed a Cookbook [pull request](https://github.com/NASA-Openscapes/earthdata-cloud-cookbook/pull/171) from Andy Barrett. ([video](https://youtu.be/2_F5Kr6gM1I), 19 min). Some generic mechanics of reviewing a pull request in GitHub are demonstrated in a screenshare ([video](https://youtu.be/ZiG4-d5vT30), 7 min 41 sec). - -In reviewing a pull request with lots of changes, it can be helpful to have windows open to view both the GitHub browser and the 2i2c Hub showing the Cookbook preview. +### Review a pull request From the pull request page in GitHub browser, look at the elements of the pull request. -*TODO: add screenshot of a PR page like the one in Cookbook, pull-request-example.png* - -![](images/pull-request-example.png) + - Start with Conversation tab: - We can see all commits and comments on what Andy has worked on @@ -67,26 +44,33 @@ From the pull request page in GitHub browser, look at the elements of the pull r - Commit tab: - More details on the commits that we saw under Conversation. When we click on one of the commits, we can see line by line what has changed under that commit (green lines are added, red lines have been removed) - Files Changed tab: - - Often easier here to assess all the files that changed across the commits + - View all the files that changed across the commits - In Nav bar: Orange dot box signifies modified; Green plus box means something's been added; Red minus box means deleted; Grey arrow box means renamed. - Checks tab: - - Shows status of the Github Action that renders and deploys the Cookbook. We can know whether this PR has the ability to be deployed + - Shows status of the Github Action that renders and deploys the site. We can know whether this Pull Request is able to be deployed. Now, switch to the 2i2c Hub to view the Cookbook preview as it would appear if the pull request was merged: - Terminal: - 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?* + - `git checkout` to the branch that has the Pull Request + - `quarto preview` - this will build the book with the author's suggested edits. + +In reviewing a pull request with lots of changes, it can be helpful to have windows open to view both the GitHub browser and the 2i2c Hub showing the Clinic site preview. + +- In GitHub under the "Files changed" tab of the PR, we can add a suggested edit by clicking the "plus" button below the line in question. Suggesting specific commits can speed the contributor's workflow compared with trying to describe what we'd like them to change. +- We can click "Start a review" button so the author gets a single email when we're done reviewing, rather than getting one notification for every edit we suggest. + +Review each individual file that has changed and come back to the main `_quarto.yml` if we see an issue with the navigation. + +Once our review is complete, we add a note in the GitHub review box and click "Approve", "Comment" or "Request changes". In the note it can be really helpful to add a note of appreciation for some aspect of the contribution, tagging the author, saying they can merge the PR after making changes, and possibly add a summary of our requested edits including the number of changes requested. Some changes in the middle of a long list of edits can be marked as hidden conversations, so this can be helpful to the author to know they've seen everything. + +### Merge your Pull Request -We can now view the changes in the built Quarto book and concurrently look at the files changed in GitHub. +As the author, you can now address the reviewer's comments and then merge your Pull Request. -- Now we see a minor issue with capitalization in the `how-tos/subset/index.md` file: - - In GitHub under the "Files changed" tab of the PR, we can add a suggested edit by clicking the "plus" button below the line in question. (See minute 17:04 in the [video](https://youtu.be/2_F5Kr6gM1I?t=1024) for the mechanics of this. Suggesting specific commits can speed the contributor's workflow compared with trying to describe what we'd like them to change.) - - We can click "Start a review" button so that Andy gets a single email when we're done reviewing, rather than getting one notification for every edit we suggest. - - We can check the "Viewed" box on each file as we go through them in the Hub. Marking files as viewed can help track our review progress by minimizing the changes visible, but does not affect the review. +### Try it out! -We will review each individual `.qmd` file and can come back to the main `_quarto.yml` if we see an issue with the main navigation. +Pair up in breakouts to make and review each other's Pull Requests -Once our review is complete, we add a note in the GitHub review and click "Approve", "Comment" or "Request changes". In the note it can be really helpful to add a note of appreciation for some aspect of the contribution, tagging the submitter, saying they can merge the PR after making changes, and possibly add a summary of our requested edits including the number of changes requested. Some changes in the middle of a long list of edits can be marked as hidden conversations, so this can be helpful to the submitter to know they've seen everything. +## View your updates in the live site (Regroup, 10 min) diff --git a/next-steps.qmd b/next-steps.qmd index 4d2a213..14bc621 100644 --- a/next-steps.qmd +++ b/next-steps.qmd @@ -2,43 +2,39 @@ title: Next Steps --- -## Troubleshooting - -### My changes don't show up in preview - -Make sure you've saved your file! There might be a slight delay depending on your JupyterHub setup. - -### Quarto render hangs / does not complete - -Check the specific notebook, are there any \`---\` throughout to denote line breaks rather than yaml? They might be causing the issue; consider deleting those. - -Also check how long the first raw cell is. Are there level-1 headers (`#`)? Try removing them. - ## Where to get help and learn more -- +### Quarto +- +- [A video to jumpstart your Quarto journey](https://quarto.org/docs/blog/posts/2023-05-15-get-started/), by Mine Çetinkaya-Rundel, May, 2023 (23 mins). *This is in RStudio IDE so will look different in the Hub.* Includes: + - Inserting [cross references](https://quarto.org/docs/authoring/cross-references.html) to tables and figures + - Adding a [citation](https://quarto.org/docs/visual-editor/technical.html#citations) from a DOI + - Seamlessly switching between output formats as well as creating [multi-format documents](https://quarto.org/docs/output-formats/html-multi-format.html) + - Customizing the [output location](https://quarto.org/docs/presentations/revealjs/#output-location) of code in presentations + - Creating a [website](https://quarto.org/docs/websites/) from scratch - [A Quarto tip a day](https://mine-cetinkaya-rundel.github.io/quarto-tip-a-day/), by Mine Çetinkaya-Rundel, July 2022 +### GitHub + +- [Reviewing a pull request](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/contributing/workflow.html#review-a-pull-request) (with videos), in the NASA Earthdata Cloud Cookbook +- [Tidyteam code review principles](https://code-review.tidyverse.org/), recommended by Andy Teucher +- Openscapes lesson on [GitHub Strategies](https://openscapes.github.io/series/core-lessons/github/), the GitHub Clinic +- Setting up Git credentials under [Tracking Changes](https://nasa-openscapes.github.io/2021-Cloud-Hackathon/tutorials/00_Setup.html#step-5.-tracking-changes-optional), in the 2021 Cloud Hackathon + ## Where to contribute We can use these skills to contribute to many Quarto websites and books. - [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/) -- [NASA Openscapes site](https://nasa-openscapes.github.io/) +- [NASA Openscapes](https://nasa-openscapes.github.io/) - e.g. add a link to your slides or recording of a presentation - [Openscapes Approach Guide](https://openscapes.github.io/approach-guide/) -- [Openscapes Champions Lessons Series](https://openscapes.github.io/series) +## Other example Quarto sites -## Example Quarto sites - -- [NASA Openscapes](https://nasa-openscapes.github.io/) -- [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/) - [2021 NASA Cloud Hackathon](https://nasa-openscapes.github.io/2021-Cloud-Hackathon/) - [Openscapes Champions Lessons Series](https://openscapes.github.io/series) -- [Openscapes Approach Guide](https://openscapes.github.io/approach-guide/) - [Faylab Lab Manual](https://thefaylab.github.io/lab-manual/) -- [A Quarto tip a day](https://mine-cetinkaya-rundel.github.io/quarto-tip-a-day/), by Mine Çetinkaya-Rundel See many more examples at the [Quarto gallery](https://quarto.org/docs/gallery/)! diff --git a/setup-explore.qmd b/setup-explore.qmd index 4de2de1..8ee6243 100644 --- a/setup-explore.qmd +++ b/setup-explore.qmd @@ -3,8 +3,6 @@ title: "Setup and Explore" editor: visual --- -*TODO: Do Welcome, then Setup Part 1: Hub login, then Explore while Hub is initiating. Setup Part 2: clone, branch. Preview site is on next page: step 1 in Lessons: Edit Quarto site.* - ## Setup Part 1: Log in to the Hub Go to the Hub \> log in with your GitHub Account \> select the Python server. @@ -38,11 +36,7 @@ Most of these are pages, but you'll see that "Lessons" has an arrow `>`; it is a ### The website's source repo - - -Let's go to this website's GitHub repository (or "repo"), . You can also click there from any page in this clinic website by clicking the GitHub Octocat icon underneath the Openscapes logo in the left navbar. +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. ::: callout-tip To open a link in a new browser tab, hold command on Mac, or control on a PC, then click. @@ -50,37 +44,10 @@ To open a link in a new browser tab, hold command on Mac, or control on a PC, th **Have a look at the filenames.** We can recognize the names of the webpages we see (and listed above), and they have red arrows marking them in the image below. Note that most files in this repo are `.qmd` files. These are plain text Quarto files that can combine Markdown text with code. `index.qmd` is the home page. When we click inside the `lessons` folder we see more `.qmd` files and an `images` folder that holds images used in the pages inside the Lessons section of the site. -*TODO: replace screenshots; red arrows for lessons, next-steps, setup (rename setup-explore)* - -*TODO: take text from `_render-vs-preview.qmd` then delete* +*TODO: replace screenshots; red arrows for lessons* ![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%"} -### Quarto Basic Workflow - -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. - -How do you work in Quarto? You can use whichever tool you're comfortable with (Jupyter, RStudio, GitHub, VS Code, etc). Developing your Quarto site will have the same basic workflow, no matter which tool you use. It is very iterative. - -1. Authoring: write text, code, images, etc in a file. Supported files include `.md`, `.Rmd`, `.qmd`, `.ipynb`... -2. Update `_quarto.yml` as needed (for example, if you've created a new file you'd like included in your site) -3. Render individual files and/or the whole website -4. Repeat, repeat, repeat -5. Commit and push your updates to GitHub, they will publish automatically! -6. Repeat all of the above to make the website as you'd like! - - - - ## Setup Part 2: Clone the Quarto Clinic repo After our Hub server has loaded (Setup Part 1), we'll clone the Quarto Clinic repository into the Hub.