From e09e991bcb18b99071091fd6068ac8bb7aaa6054 Mon Sep 17 00:00:00 2001 From: Stefanie Butland Date: Mon, 27 May 2024 14:43:22 -0700 Subject: [PATCH 1/4] rm practice folder, put things back to workflows folder only, comment out code in demo.qmd for now --- _freeze/site_libs/clipboard/clipboard.min.js | 7 ++ practice/index.qmd | 5 - {practice => workflows}/demo.qmd | 35 ++---- workflows/jupyter.qmd | 125 +++---------------- 4 files changed, 36 insertions(+), 136 deletions(-) create mode 100644 _freeze/site_libs/clipboard/clipboard.min.js delete mode 100644 practice/index.qmd rename {practice => workflows}/demo.qmd (59%) diff --git a/_freeze/site_libs/clipboard/clipboard.min.js b/_freeze/site_libs/clipboard/clipboard.min.js new file mode 100644 index 0000000..1103f81 --- /dev/null +++ b/_freeze/site_libs/clipboard/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.11 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return n={686:function(t,e,n){"use strict";n.d(e,{default:function(){return b}});var e=n(279),i=n.n(e),e=n(370),u=n.n(e),e=n(817),r=n.n(e);function c(t){try{return document.execCommand(t)}catch(t){return}}var a=function(t){t=r()(t);return c("cut"),t};function o(t,e){var n,o,t=(n=t,o="rtl"===document.documentElement.getAttribute("dir"),(t=document.createElement("textarea")).style.fontSize="12pt",t.style.border="0",t.style.padding="0",t.style.margin="0",t.style.position="absolute",t.style[o?"right":"left"]="-9999px",o=window.pageYOffset||document.documentElement.scrollTop,t.style.top="".concat(o,"px"),t.setAttribute("readonly",""),t.value=n,t);return e.container.appendChild(t),e=r()(t),c("copy"),t.remove(),e}var f=function(t){var e=1. @@ -14,6 +12,9 @@ To learn more about Quarto see . When you click the **Render** button a document will be generated that includes both content and the output of embedded code. You can embed code like this: +TODO: un-comment code + + The `echo: false` option disables the printing of code (only output is displayed). -## insert an image - -with alt text, edit size - e.g. NASA Openscapes logo - -# GitHub practice from the browser - -Working on GitHub.com, we contribute changes through **commits**. You'll practice creating several commits by making small edits to a file, writing commit messages, and committing changes to see them posted nicely online to communicate our work. You'll practice with the file with your name on it; everyone has their own file to practice with. - -## Task 1: Commit an edit from the browser +## Task: Edit a `.qmd` page -Let's edit this file by clicking the pencil icon at the top-right of the file. +TODO: Edit down to what we need. -Next, make an edit to the text in this file. One idea is to fix this tpyo. - -Finally, we will commit these edits to GitHub. To do this, press the green "Commit Changes..." button. Committing changes has two steps: write a human-readable Commit message, and press the green button to commit changes. - -Note: In the browser, GitHub will suggest "Update file.md" as the commit message. But you can be more descriptive - practice writing commit messages that help you remember detail about what you changed. - -## Task 2: Practice Markdown - -Now let's practice Markdown and commit another edit to this file. +Now let's practice Markdown and commit an edit to this file. This file is written in Markdown, which formats text on the web. To see the Markdown that results in the following formatting, click the pencil icon to edit, or click 'Raw' to inspect it. For example, with Markdown: @@ -76,6 +62,3 @@ We can include an image with the same `[]()` pattern, by adding a preceding excl Your turn! Change or add something in Markdown and make another commit: write a human-readable commit message, and press the green button to commit changes. -## NOTES - -It's a lot to get familiar with markdown if you haven't used it previously! diff --git a/workflows/jupyter.qmd b/workflows/jupyter.qmd index 5ce07d3..01a2467 100644 --- a/workflows/jupyter.qmd +++ b/workflows/jupyter.qmd @@ -1,5 +1,5 @@ --- -title: From Jupyter +title: From JupyterHub --- You can interact with Quarto through JupyterLab or JupyterHub. Your Jupyter setup will involve `.ipynb` notebooks and the command line. [Quarto's JupyterLab tutorials](https://quarto.org/docs/get-started/hello/jupyter.html) has great instructions on getting started with JupyterLab, including computations and authoring. @@ -8,123 +8,30 @@ Here we will demonstrate how to work with this Quarto tutorial site in JupyterHu ## Setup +TODO: add login to the Hub + ### JupyterHub Our JupyterHub is already setup with python environments as well as Quarto (through [nasa-openscapes/corn](https://github.com/nasa-openscapes/corn)), so there is no further installation required. ### Clone your repo -You'll start by cloning your repository into JupyterHub. 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-website-tutorial -cd quarto-website-tutorial -``` +You'll start by cloning your repository into JupyterHub. -### Install Quarto +**Option A:** Use the Git tab to Clone repo -Not needed - Quarto is already installed on the NASA-Openscapes JupyterHub! But to install elsewhere you would do so from . +TODO: add screenshot from doc -Quarto is a Command Line Interface (CLI), like git. Once download is complete, follow the installation prompts on your computer like you do for other software. You won't see an application to click on when it is installed. - -*Note for Mac users: If you do not have administrative privileges, please select "Install for me only" during the Destination Selection installation step (you will first click on "Change Install Location" at the Installation Type step).* - -You can check to confirm that Quarto is installed properly from the command line: +**Option B:** Do this by opening a terminal (File > New > Terminal). In the Terminal, `git clone` your repository and `cd` into it: ``` bash -quarto check install +git clone https://github.com/openscapes/quarto-clinic +cd quarto-clinic ``` -::: {.callout-note collapse="true"} -## Additional checks - -You can also run: - -- `quarto check knitr` to locate R, verify we have the rmarkdown package, and do a basic render -- `quarto check jupyter` to locate Python, verify we have Jupyter, and do a basic render -- `quarto check` to run all of these checks together -::: -::: {.callout-tip collapse="true"} -## Historical aside: Install Quarto in a docker container -In Summer 2021 some NASA Mentors trying to install quarto locally was not an option, but they were able to install it inside a container using the following `Dockerfile`: - -``` bash -#| fold: true -#| summary: "Show the Dockerfile" - -############################## -# This Dockerfile installs quarto and then runs quarto serve against the -# internal /home/quarto/to_serve. -# -# BUILD -# ----- -# To build this container, run -# -# docker build -t quarto_serve . -# -# Add the --no-cache option to force docker to build fresh and get the most -# recent version of quarto. -# -# -# RUN -# --- -# 1. Find the directory you want quarto to serve. Let's call this /PATH/TO/earthdata-cloud-cookbook. -# 2. Run docker: -# -# docker run --rm -it -p 4848:4848 -v /PATH/TO/earthdata-cloud-cookbook:/home/quarto/to_serve quarto_serve -# -# 3. Open your browser and go to http://127.0.0.1:4848/ -# -############################## - -FROM ubuntu:hirsute - -###### -# Install some command line tools we'll need -###### -RUN apt-get update -RUN apt-get -y install wget -RUN apt-get -y install gdebi-core -RUN apt-get -y install git - - -###### -# Install quarto (https://quarto.org/) -###### - -# This is a quick and dirty way of getting the newest version number from -# https://github.com/quarto-dev/quarto-cli/releases/latest. What's happening is -# we're pulling the version number out of the redirect URL. This will end up -# with QVER set to something like 0.2.11. -RUN QVER=`wget --max-redirect 0 https://github.com/quarto-dev/quarto-cli/releases/latest 2>&1 | grep "Location" | sed 's/L.*tag\/v//' | sed 's/ .*//'` \ - && wget -O quarto.deb "https://github.com/quarto-dev/quarto-cli/releases/download/v$QVER/quarto-$QVER-amd64.deb" -RUN gdebi -n quarto.deb - -# Run this to make sure quarto installed correctly -RUN quarto check install - - -###### -# Create a non-root user called quarto -###### -RUN useradd -ms /bin/bash quarto -USER quarto -RUN mkdir /home/quarto/to_serve -WORKDIR /home/quarto/to_serve - - -###### -# Start quarto serve -###### - -CMD quarto serve --no-browse --host 0.0.0.0 --port 4848 -``` - -::: - -## Quarto preview +## Preview the site (aka Quarto preview) Let's start off by previewing our quarto site locally. In Terminal, type `quarto preview`, which will provide a URL with a preview of our site! @@ -137,17 +44,23 @@ quarto preview Copy this URL into another browser window; and arrange them 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"} +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. + ### Make a small change and preview it -Now we'll be able to see live changes in the preview as we edit in our `.md` files. Let's try it: Change the date in `index.md` by opening it from the file directory. Change to today's date, and save. Your 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! +TODO: move this below ipynb section? + +Now we'll be able to see live changes in the preview as we edit in our `.qmd` files. Let's try it: Change the date in `index.qmd` by opening it from the file directory. Change to today's date, and save. Your 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! ## Create a new `.ipynb` page Let's add a new page to our site. Instead of an `.md` file like the others, let's add a `.ipynb` file. -File \> New \> Notebook. Accept the default kernel by clicking Select. +File > New > Notebook. Accept the default kernel by clicking Select. ### First chunk: raw yaml @@ -215,6 +128,8 @@ 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 # + Add `- python-example.ipynb` to line 46, making sure that your indentation aligns with the other pages. ![](images/jupyter-python-example.png){fig-align="center"} From b4a1ed28e2756337f1698c99baa21d13fdea6476 Mon Sep 17 00:00:00 2001 From: Stefanie Butland Date: Mon, 27 May 2024 14:51:35 -0700 Subject: [PATCH 2/4] un-comment demo.qmd code; I can't remember how to force code not to run. Site rendering still fails locally because of the code --- _quarto.yml | 4 +--- workflows/demo.qmd | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/_quarto.yml b/_quarto.yml index d93c355..79bfee0 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -39,9 +39,7 @@ website: - section: workflows/index.qmd contents: - href: workflows/jupyter.qmd - - section: practice/index.qmd - contents: - - practice/demo.qmd + text: From JupyterHub - href: where-to-contribute.qmd text: Where to Contribute diff --git a/workflows/demo.qmd b/workflows/demo.qmd index 23e4a14..8aa1c1b 100644 --- a/workflows/demo.qmd +++ b/workflows/demo.qmd @@ -12,9 +12,7 @@ To learn more about Quarto see . When you click the **Render** button a document will be generated that includes both content and the output of embedded code. You can embed code like this: -TODO: un-comment code - + The `echo: false` option disables the printing of code (only output is displayed). From 32d3bd8127e6974aa7286fde53572d275fdad6eb Mon Sep 17 00:00:00 2001 From: Stefanie Butland Date: Mon, 27 May 2024 15:58:33 -0700 Subject: [PATCH 3/4] remove python code from demo.qmd, commit freeze --- _freeze/workflows/demo/execute-results/html.json | 15 +++++++++++++++ workflows/demo.qmd | 9 +++------ 2 files changed, 18 insertions(+), 6 deletions(-) create mode 100644 _freeze/workflows/demo/execute-results/html.json diff --git a/_freeze/workflows/demo/execute-results/html.json b/_freeze/workflows/demo/execute-results/html.json new file mode 100644 index 0000000..7fa649a --- /dev/null +++ b/_freeze/workflows/demo/execute-results/html.json @@ -0,0 +1,15 @@ +{ + "hash": "8c458dbde28009c4246bee49f47b250f", + "result": { + "engine": "knitr", + "markdown": "---\ntitle: \"`demo.qmd` aka Quarto Practice\"\n---\n\n\nQuarto enables you to weave together content and executable code into a finished document. \n\nThis `demo.qmd` file has example R and python code chunks, Markdown-formatted text, and examples for adding images and hyperlinks.\n\nTo learn more about Quarto see .\n\n## Running Code\n\nWhen you click the **Render** button a document will be generated that includes both content and the output of embedded code. You can embed code like this:\n\nYou can add options to executable code like this\n\nTODO: day before clinic, make this Python code (don't add screenshot - fewer files to for folks to get distracted with, lighter weight repo)\n\n\n::: {.cell}\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] 4\n```\n\n\n:::\n:::\n\n\n\nThe `echo: false` option disables the printing of code (only output is displayed).\n\n\n## Task: Edit a `.qmd` page\n\nTODO: Edit down to what we need. \n\nNow let's practice Markdown and commit an edit to this file.\n\nThis file is written in Markdown, which formats text on the web. To see the Markdown that results in the following formatting, click the pencil icon to edit, or click 'Raw' to inspect it. For example, with Markdown:\n\nWe can make words **bold** or *italic*.\n\n### We can make headers.\n\nWe can make lists – *note that lists need an empty line before list items!*\n\n1. bananas\n2. tamales\n3. cakes\n\nWe can make hyperlinks in [Markdown](https://quarto.org/docs/authoring/markdown-basics.html) using the `[]()` pattern: you put words to hyperlink in `[]` and the URL in `()`. For example:\n\n> [This twitter thread](https://twitter.com/allison_horst/status/1287772985630191617) describes the palmerpenguins R package. Learn more on the [palmerpenguins webpage](https://allisonhorst.github.io/palmerpenguins).\n\nWe can make an indented quote block with the `>` symbol, as in the example above.\n\nWe can include an image with the same `[]()` pattern, by adding a preceding exclamation point: `![]()`. For example:\n\n[![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=\"250\"}](https://openscapes.org/)\n\n*Note how we can add alt text for the image, manage the image size, and link the image to a URL* \n\nYour turn! Change or add something in Markdown and make another commit: write a human-readable commit message, and press the green button to commit changes.\n\n", + "supporting": [], + "filters": [ + "rmarkdown/pagebreak.lua" + ], + "includes": {}, + "engineDependencies": {}, + "preserve": {}, + "postProcess": true + } +} \ No newline at end of file diff --git a/workflows/demo.qmd b/workflows/demo.qmd index 8aa1c1b..208dbbb 100644 --- a/workflows/demo.qmd +++ b/workflows/demo.qmd @@ -12,14 +12,11 @@ To learn more about Quarto see . When you click the **Render** button a document will be generated that includes both content and the output of embedded code. You can embed code like this: - -```{r} -1 + 1 -``` - You can add options to executable code like this -```{python} +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 2 * 2 ``` From a839b26e5edb483d7cca74f424b5100bbe2fa7f5 Mon Sep 17 00:00:00 2001 From: Stefanie Butland Date: Mon, 27 May 2024 16:01:06 -0700 Subject: [PATCH 4/4] delete a freeze file --- _freeze/workflows/demo/execute-results/html.json | 15 --------------- 1 file changed, 15 deletions(-) delete mode 100644 _freeze/workflows/demo/execute-results/html.json diff --git a/_freeze/workflows/demo/execute-results/html.json b/_freeze/workflows/demo/execute-results/html.json deleted file mode 100644 index 7fa649a..0000000 --- a/_freeze/workflows/demo/execute-results/html.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "hash": "8c458dbde28009c4246bee49f47b250f", - "result": { - "engine": "knitr", - "markdown": "---\ntitle: \"`demo.qmd` aka Quarto Practice\"\n---\n\n\nQuarto enables you to weave together content and executable code into a finished document. \n\nThis `demo.qmd` file has example R and python code chunks, Markdown-formatted text, and examples for adding images and hyperlinks.\n\nTo learn more about Quarto see .\n\n## Running Code\n\nWhen you click the **Render** button a document will be generated that includes both content and the output of embedded code. You can embed code like this:\n\nYou can add options to executable code like this\n\nTODO: day before clinic, make this Python code (don't add screenshot - fewer files to for folks to get distracted with, lighter weight repo)\n\n\n::: {.cell}\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] 4\n```\n\n\n:::\n:::\n\n\n\nThe `echo: false` option disables the printing of code (only output is displayed).\n\n\n## Task: Edit a `.qmd` page\n\nTODO: Edit down to what we need. \n\nNow let's practice Markdown and commit an edit to this file.\n\nThis file is written in Markdown, which formats text on the web. To see the Markdown that results in the following formatting, click the pencil icon to edit, or click 'Raw' to inspect it. For example, with Markdown:\n\nWe can make words **bold** or *italic*.\n\n### We can make headers.\n\nWe can make lists – *note that lists need an empty line before list items!*\n\n1. bananas\n2. tamales\n3. cakes\n\nWe can make hyperlinks in [Markdown](https://quarto.org/docs/authoring/markdown-basics.html) using the `[]()` pattern: you put words to hyperlink in `[]` and the URL in `()`. For example:\n\n> [This twitter thread](https://twitter.com/allison_horst/status/1287772985630191617) describes the palmerpenguins R package. Learn more on the [palmerpenguins webpage](https://allisonhorst.github.io/palmerpenguins).\n\nWe can make an indented quote block with the `>` symbol, as in the example above.\n\nWe can include an image with the same `[]()` pattern, by adding a preceding exclamation point: `![]()`. For example:\n\n[![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=\"250\"}](https://openscapes.org/)\n\n*Note how we can add alt text for the image, manage the image size, and link the image to a URL* \n\nYour turn! Change or add something in Markdown and make another commit: write a human-readable commit message, and press the green button to commit changes.\n\n", - "supporting": [], - "filters": [ - "rmarkdown/pagebreak.lua" - ], - "includes": {}, - "engineDependencies": {}, - "preserve": {}, - "postProcess": true - } -} \ No newline at end of file