From 857f53ae0976e11b5e413e71774f1172f7c51e0b Mon Sep 17 00:00:00 2001 From: Julia Stewart Lowndes Date: Wed, 19 Jun 2024 12:53:11 -0700 Subject: [PATCH 1/5] move example sites to ending --- index.qmd | 11 ----------- next-steps.qmd | 13 +++++++++++++ 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/index.qmd b/index.qmd index bb78c7f..cf1963a 100644 --- a/index.qmd +++ b/index.qmd @@ -33,14 +33,3 @@ Quarto can be used to create dynamic content with Python, R, Julia, and Observab [Quarto.org](https://quarto.org) is the go-to place for full documentation and more tutorials! -## 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/next-steps.qmd b/next-steps.qmd index bbcd3af..4d2a213 100644 --- a/next-steps.qmd +++ b/next-steps.qmd @@ -29,3 +29,16 @@ We can use these skills to contribute to many Quarto websites and books. - 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) + + +## 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/)! From 45e7fdee739e3b9819492f557842adbe52198ccd Mon Sep 17 00:00:00 2001 From: Julia Stewart Lowndes Date: Wed, 19 Jun 2024 13:41:44 -0700 Subject: [PATCH 2/5] tidying: don't think we need lua file --- _quarto.yml | 1 - include-files.lua | 115 ---------------------------------------------- 2 files changed, 116 deletions(-) delete mode 100644 include-files.lua diff --git a/_quarto.yml b/_quarto.yml index 5583106..db461ec 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -60,7 +60,6 @@ format: filters: - - include-files.lua - quarto diff --git a/include-files.lua b/include-files.lua deleted file mode 100644 index b933836..0000000 --- a/include-files.lua +++ /dev/null @@ -1,115 +0,0 @@ ---- include-files.lua – filter to include Markdown files ---- ---- Copyright: © 2019–2021 Albert Krewinkel ---- License: MIT – see LICENSE file for details - --- Module pandoc.path is required and was added in version 2.12 -PANDOC_VERSION:must_be_at_least '2.12' - -local List = require 'pandoc.List' -local path = require 'pandoc.path' -local system = require 'pandoc.system' - ---- Get include auto mode -local include_auto = false -function get_vars (meta) - if meta['include-auto'] then - include_auto = true - end -end - ---- Keep last heading level found -local last_heading_level = 0 -function update_last_level(header) - last_heading_level = header.level -end - ---- Update contents of included file -local function update_contents(blocks, shift_by, include_path) - local update_contents_filter = { - -- Shift headings in block list by given number - Header = function (header) - if shift_by then - header.level = header.level + shift_by - end - return header - end, - -- If image paths are relative then prepend include file path - Image = function (image) - if path.is_relative(image.src) then - image.src = path.normalize(path.join({include_path, image.src})) - end - return image - end, - -- Update path for include-code-files.lua filter style CodeBlocks - CodeBlock = function (cb) - if cb.attributes.include and path.is_relative(cb.attributes.include) then - cb.attributes.include = - path.normalize(path.join({include_path, cb.attributes.include})) - end - return cb - end - } - - return pandoc.walk_block(pandoc.Div(blocks), update_contents_filter).content -end - ---- Filter function for code blocks -local transclude -function transclude (cb) - -- ignore code blocks which are not of class "include". - if not cb.classes:includes 'include' then - return - end - - -- Markdown is used if this is nil. - local format = cb.attributes['format'] - - -- Attributes shift headings - local shift_heading_level_by = 0 - local shift_input = cb.attributes['shift-heading-level-by'] - if shift_input then - shift_heading_level_by = tonumber(shift_input) - else - if include_auto then - -- Auto shift headings - shift_heading_level_by = last_heading_level - end - end - - --- keep track of level before recusion - local buffer_last_heading_level = last_heading_level - - local blocks = List:new() - for line in cb.text:gmatch('[^\n]+') do - if line:sub(1,2) ~= '//' then - local fh = io.open(line) - if not fh then - io.stderr:write("Cannot open file " .. line .. " | Skipping includes\n") - else - local contents = pandoc.read(fh:read '*a', format).blocks - last_heading_level = 0 - -- recursive transclusion - contents = system.with_working_directory( - path.directory(line), - function () - return pandoc.walk_block( - pandoc.Div(contents), - { Header = update_last_level, CodeBlock = transclude } - ) - end).content - --- reset to level before recursion - last_heading_level = buffer_last_heading_level - blocks:extend(update_contents(contents, shift_heading_level_by, - path.directory(line))) - fh:close() - end - end - end - return blocks -end - -return { - { Meta = get_vars }, - { Header = update_last_level, CodeBlock = transclude } -} From fe2d3be7ae5c7c712f62a4a368e137a8edd4e4b9 Mon Sep 17 00:00:00 2001 From: Julia Stewart Lowndes Date: Wed, 19 Jun 2024 13:57:38 -0700 Subject: [PATCH 3/5] reduce pop, thinking about how to teach out loud --- index.qmd | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/index.qmd b/index.qmd index cf1963a..55fa2de 100644 --- a/index.qmd +++ b/index.qmd @@ -11,17 +11,19 @@ The ability for Quarto to streamline collaboration has been so cool and importan **To begin**, you should have a GitHub account with access to the 2i2c Openscapes JupyterHub. -## Purpose, Outcomes, Process ([POP](https://suzannehawkes.com/2010/04/09/pop-everything/)) +## Our Plan today -**Purpose:** NASA Openscapes Mentors learn workflows with Quarto and GitHub for contributing to the [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/) or any site or book made with Quarto. An opportunity for Mentors to connect and skill-build together. +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/). -**Outcomes:** Mentors build skills and are more equipped and empowered to contribute. This is a new clinic we can reuse and build on. +This is a 1.5-hr clinic that has demos and time for hands-on practice in breakout rooms. -**Process:** A 1.5-hr clinic that can be used to teach or as self-paced learning. with demo's and hands-on practice to guide folks through contributing to existing Quarto sites & books. Analogous to our GitHub Clinic. The clinic content is contained in this website that is built with Quarto on GitHub; there are no accompanying slide decks. +**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. -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. -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. + + + From 673aba151ca6319bfdf7184a47b7b1d469cefc74 Mon Sep 17 00:00:00 2001 From: Julia Stewart Lowndes Date: Wed, 19 Jun 2024 13:58:01 -0700 Subject: [PATCH 4/5] move basic workflow to setup-explore --- lessons/index.qmd | 11 ----------- setup-explore.qmd | 21 ++++++++++++++++++++- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/lessons/index.qmd b/lessons/index.qmd index d16de73..2324e80 100644 --- a/lessons/index.qmd +++ b/lessons/index.qmd @@ -4,17 +4,6 @@ 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* -## Basic Workflow - -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! - ## Authoring *TODO: Move to "Edit a Quarto site"* diff --git a/setup-explore.qmd b/setup-explore.qmd index 98df25c..4de2de1 100644 --- a/setup-explore.qmd +++ b/setup-explore.qmd @@ -38,7 +38,9 @@ Most of these are pages, but you'll see that "Lessons" has an arrow `>`; it is a ### The website's source repo -*TODO: If we will make a new repo for every Clinic, we'll need to update the repo link below, every time.* + 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. @@ -54,6 +56,21 @@ To open a link in a new browser tab, hold command on Mac, or control on a PC, th ![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. From b76f56e87bbbbcce6c877ef2495ac507b74177ad Mon Sep 17 00:00:00 2001 From: Julia Stewart Lowndes Date: Wed, 19 Jun 2024 14:02:59 -0700 Subject: [PATCH 5/5] Would it work to delete demo.qmd all together? --- _quarto.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_quarto.yml b/_quarto.yml index db461ec..4a86e5b 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -41,8 +41,8 @@ website: contents: - href: lessons/part1-quarto.qmd text: Edit a Quarto site - - href: lessons/demo.qmd - text: demo.qmd practice file +# - href: lessons/demo.qmd + # text: demo.qmd practice file - href: lessons/part2-github.qmd text: Contribute via GitHub - href: next-steps.qmd