Actions v2 (#19)

revamp actions and documentation for v2

Author: cscheid

README.md

@@ -2,7 +2,11 @@
 
 This repository stores [Github Actions](https://github.com/features/actions) around Quarto (https://quarto.org/)
 
-1. [quarto-dev/quarto-actions/install-quarto](https://github.com/quarto-dev/quarto-actions/tree/master/install-quarto) - Install Quarto binary
+1. [quarto-dev/quarto-actions/setup](https://github.com/quarto-dev/actions/tree/master/setup) - Install Quarto
+2. [quarto-dev/quarto-actions/render](https://github.com/quarto-dev/actions/tree/master/render) - Render project
+3. [quarto-dev/quarto-actions/publish](https://github.com/quarto-dev/actions/tree/master/publish) - Publish project
+
+We recommend using `v2` for your actions, and our examples all use `v2`.
 
 ## Examples
 
@@ -14,11 +18,5 @@ This repository is using [recommended release management for actions](https://do
 
 * Github releases with tags are used for updates on the actions. 
 * Semantic versioning is used, with major, minor and possibly patch release. 
-* Major version (such as `v1`) will always point to the last minor or patch release for this major version. (when `v1.0.2` is out, `v1` will point to this update to). This means using `quarto-dev/quarto-actions/install-quarto@v1` in your workflow file will automatically get the updated versions. Using `quarto-dev/quarto-actions/[email protected]` will pin a specific release.
-* Major version change (`v1` to `v2`) will often come with a possible breaking change, and a workflow would require manual update.
-
-Example:
-
-```yaml
-- uses: quarto-dev/quarto-actions/install-quarto@v1
-```
+* Major version (such as `v1`) will always point to the last minor or patch release for this major version. (when `v1.0.2` is out, `v1` will point to this update to). This means using `quarto-dev/quarto-actions/setup@v2` in your workflow file will automatically get the updated versions. Using `quarto-dev/quarto-actions/[email protected]` will pin a specific release.
+* Major version change (`v1` to `v2`) will often come with a possible breaking change, and a workflow would require manual update.

examples/README.md

@@ -1,41 +1,14 @@
-# Examples of workflow YAML files
+# Using Quarto Actions: Examples
 
-You'll find here some generic workflows for Quarto projects.
+* [Basics](./example-01-basics.md)
+* [Freeze](./example-02-freeze.md)
+* [Other dependencies](./example-03-other-dependencies.md)
 
-## Templates
-
-### Quarto Book
-
-- [`quarto-book-gh-pages`](./quarto-book-gh-pages.yaml): Render an HTML Quarto Book and deploy to github pages
-
-- [`quarto-book-netlify`](./quarto-book-netlify.yaml): Render an HTML Quarto Book and deploy to [Netlify](https://www.netlify.com). You must also config 2 github secrets:
-  - `NETLIFY_AUTH_TOKEN`: [Personal access tokens](https://app.netlify.com/user/applications#personal-access-tokens) > New access token
-  - `NETLIFY_SITE_ID`: team page > your site > Settings > Site details > Site information > API ID
-  - More details see [this Netlify action](https://github.com/nwtgck/actions-netlify).
-
-### How to use ?
-
-1. Download one of the YAML workflows into the `.github/workflows` folder of your project where [Github Actions Workflows](https://docs.github.com/en/actions/quickstart) are stored
-2. Edit the workflow file according to your needs, especially adding steps to setup any computation engines you may need (Python, R, Julia, ...). 
-
-See the repository examples using Quarto actions below.
-
-#### Specific for R users
-
-With the [**usethis**](https://usethis.r-lib.org/) package, R users can easily add one of these example workflow in a project using [`usethis::use_github_action()`](https://usethis.r-lib.org/reference/github_actions.html) and the full URL of the raw YAML file. Example (where `v1` indicates the version tag):
-
-```r
-usethis::use_github_action(
-  url = "https://raw.githubusercontent.com/quarto-dev/quarto-actions/v1/examples/quarto-book-gh-pages.yaml"
-)
-```
-
-This will download the YAML file into the `.github/workflows/` folder of your project, where it can be further adapted to your project (like adding a step to install R and R dependencies).
 
 ## Repositories using Quarto actions
 
-- [Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/) ([source](https://github.com/NASA-Openscapes/earthdata-cloud-cookbook)). Book with `*.md` and `.ipynb` is built with Quarto and Python in GHA and deployed to Github Pages. [workflow file](https://github.com/NASA-Openscapes/earthdata-cloud-cookbook/blob/main/.github/workflows/quarto-render.yml).
+- [Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/) ([source](https://github.com/NASA-Openscapes/earthdata-cloud-cookbook), [workflow file](https://github.com/NASA-Openscapes/earthdata-cloud-cookbook/blob/main/.github/workflows/quarto-render.yml)) This book contains `.md` and `.ipynb` files, and is built with Quarto and Python in GHA, and deployed to Github Pages. 
 
-- [R Manuals Quarto website](https://rstudio.github.io/r-manuals/) ([source](https://github.com/rstudio/r-manuals)) uses a complex workflow to build several books with R and Quarto and organizes them in a unique website deployed to Github pages. [workflow file](https://github.com/rstudio/r-manuals/blob/main/.github/workflows/build-website.yaml).
+- [R Manuals Quarto website](https://rstudio.github.io/r-manuals/) ([source](https://github.com/rstudio/r-manuals), [workflow file](https://github.com/rstudio/r-manuals/blob/main/.github/workflows/build-website.yaml)) This projects uses a workflow to build several books with R and Quarto and organizes them in a website deployed to Github pages.
 
-- [Pathology Atlas](https://www.patolojiatlasi.com/EN) is a multilingual website ([source](https://github.com/patolojiatlasi/patolojiatlasi.github.io)). Two versions are rendered and deployed using Github Action. [workflow file](https://github.com/patolojiatlasi/patolojiatlasi.github.io/blob/main/.github/workflows/Quarto-Render-Bilingual-Book-Push-Tweet-Updates.yml)
+- [Pathology Atlas](https://www.patolojiatlasi.com/EN) ([source](https://github.com/patolojiatlasi/patolojiatlasi.github.io), [workflow file](https://github.com/patolojiatlasi/patolojiatlasi.github.io/blob/main/.github/workflows/Quarto-Render-Bilingual-Book-Push-Tweet-Updates.yml)) This multilingual website is rendered in two versions and deployed using Github Actions. 

examples/example-01-basics.md

@@ -0,0 +1,58 @@
+# Quarto Actions: Basics
+
+The simplest workflow using Quarto Actions uses the `setup` and `publish` actions: [quarto-publish-example.yml](quarto-publish-example.yml).
+
+## GitHub Pages
+
+1. **Add the GitHub Actions workflow to your project**
+
+   Copy [quarto-publish-example.yml](quarto-publish-example.yml) to `.github/workflows/quarto-publish.yml`. Uncomment the "Publish to GitHub Pages (and render)" action. No further changes are needed to the action (in particular, do *not* edit the line below to add a secret to this file. This file has the same permissions as your repository, and might be publicly readable)
+
+Now, add and commit the workflow file you have just created, and push the result to GitHub. This should trigger a new action from GitHub that will automatically render and publish your website through GitHub pages. Note that this will create a `gh-pages` branch in your repository if one doesn't exist.
+
+
+## Netlify
+
+1. **Create Netlify auth token**
+
+   Go to Netlify's [applications page](https://app.netlify.com/user/applications), and click on "New Access Token" to create a new personal access token. Give this token a memorable name, and note the resulting string (or keep this browser window open).
+
+2. **Add Netlify auth token to your GitHub repository**
+
+   Go to the GitHub webpage for the repository that will be using this GitHub Action. Click on "Settings". On the new page, click on "Secrets", then on the dropdown "Actions". Now, on the right-hand tab, click on the "New repository secret" button to the right of the title "Actions secrets". For the "Name" field, use `NETLIFY_AUTH_TOKEN`, and for the "Value" field, paste the string you got from step 1.
+
+3. **Add the GitHub Actions workflow to your project**
+
+   Copy [quarto-publish-example.yml](quarto-publish-example.yml) to `.github/workflows/quarto-publish.yml`.
+   
+   Uncomment the "Publish to Netlify (and render)" action. No further changes are needed (in particular, do *not* edit the line below to add a secret to this file. This file has the same permissions as your repository, and might be publicly readable)
+
+4. **Add `_publish.yml` to your repository**
+
+   Quarto stores publishing metadata information in `_publish.yml`. To create this file, run `quarto publish netlify` locally once (TODO: how does this work in an IDE?).
+
+
+Finally, add and commit the files you have just created, and push the result to GitHub. This should trigger a new action from GitHub that will automatically render and publish your website through Netlify.
+
+## RStudio Connect
+
+1. **Create RStudio Connect auth token**
+
+   After logging in to your RStudio Connect server, click on your username on the top right. A sidebar should slide in from the right. Click on "API keys". On the new page, click on the "New API Key" button. Give it a memorable name and note the resulting string (or keep this browser window open).
+
+2. **Add RStudio Connect auth token to your GitHub repository**
+
+   Go to the GitHub webpage for the repository that will be using this GitHub Action. Click on "Settings". On the new page, click on "Secrets", then on the dropdown "Actions". Now, on the right-hand tab, click on the "New repository secret" button to the right of the title "Actions secrets". For the "Name" field, use `CONNECT_API_KEY`, and for the "Value" field, paste the string you got from step 1.
+
+3. **Add the GitHub Actions workflow to your project**
+
+   Copy [quarto-publish-example.yml](quarto-publish-example.yml) to `.github/workflows/quarto-publish.yml`. Uncomment the "Publish to RStudio Connect (and render)" action, and change the CONNECT_SERVER entry to the URL of your RStudio Connect server. No further changes are needed to the action (in particular, do *not* edit the line below to add a secret to this file. This file has the same permissions as your repository, and might be publicly readable)
+
+4. **Add `_publish.yml` to your repository**
+
+   Quarto stores publishing metadata information in `_publish.yml`. To create this file, run `quarto publish connect` locally once (TODO: how does this work in an IDE?).
+
+Finally, add and commit the files you have just created, and push the result to GitHub. This should trigger a new action from GitHub that will automatically render and publish your website through RStudio Connect.
+
+
+

examples/example-02-freeze.md

@@ -0,0 +1,28 @@
+# Quarto Actions: Freeze
+
+If you have computational content which cannot be executed in a CI environment (because of eg security or authentication), you can use Quarto's freezer feature.
+
+## Enabling Freeze
+
+Add the following to your `_quarto.yml` configuration:
+
+```yaml
+execute:
+  freeze: true  # never re-execute computational content during project render
+```
+
+This stops quarto from re-executing computational cells during a project render.
+
+## Adding the frozen contents to the repository
+
+From a computer that is capable of executing the content, run a file-specific `render` command to create or update the frozen content
+
+```bash
+$ quarto render name-of-file-to-freeze.qmd
+```
+
+Note that you have to specify the particular file: a call to `quarto render` will _not_ re-execute the content when `freeze: true`. Finally, add the `_freeze` top-level directory to version control so that GitHub Actions can reuse the executed content.
+
+## More
+
+See [Quarto's documentation on freeze](https://quarto.org/docs/projects/code-execution.html#freeze) for more.

examples/example-03-dependencies.md

@@ -0,0 +1,53 @@
+# Quarto Actions: Dependencies
+
+If you want to execute computational content in GitHub Actions workflows, you are going to have to install the necessary software dependencies in your action.
+
+## Installing R
+
+Add the following entry to your GitHub Actions workflow:
+
+```yaml
+- uses: r-lib/actions/setup-r@v2
+  with:
+    r-version: '4.2.0' # The R version to download (if necessary) and use.
+```
+
+If you're using `quarto-publish-example.yml`, add those right after the `# add software dependencies here` comment.
+
+### renv
+
+If you are managing your R package dependencies with `renv`, the following action will install the dependencies:
+
+```yaml
+- uses: r-lib/actions/setup-renv@v2
+  with:
+    cache-version: 1
+```
+
+See [the `setup-renv` documentation](https://github.com/r-lib/actions/tree/v2/setup-renv) for how to use `cache-version`.
+
+## Installing Jupyter
+
+Add the following entry to your GitHub Actions workflow:
+
+```yaml
+- uses: actions/setup-python@v4
+  with:
+    python-version: '3.x' # Version range or exact version of a Python version to use, using SemVer's version range syntax
+- run: pip install jupyter
+```
+
+### Using `requirements.txt`
+
+```yaml
+- uses: actions/setup-python@v4
+  with:
+    python-version: '3.x' # Version range or exact version of a Python version to use, using SemVer's version range syntax
+    cache: 'pip'
+- run: pip install jupyter # (if jupyter is not part of your requirements.txt)
+- run: pip install -r requirements.txt
+```
+
+## Installing Julia
+
+TBF.

examples/example-04-other-workflows.md

@@ -0,0 +1,10 @@
+# Using Quarto Actions: other workflows
+
+## Render without publishing
+
+If you need to render your project in a GitHub Action, but will use the output for something besides publishing (or publishing to a service not supported by `quarto publish`), then use the `render` action:
+
+```yaml
+- name: Render Quarto Project
+  uses: quarto-dev/quarto-actions/render@v2
+```

examples/quarto-book-gh-pages.yaml

@@ -0,0 +1,50 @@
+on:
+  push:
+    branches: main
+  
+  # TODO test PR trigger
+  # pull_request:
+  #   branches: main
+
+name: Render and Publish
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v2 
+        
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          # To install LaTeX to build PDF book 
+          tinytex: true 
+          # uncomment below and fill to pin a version
+          # version: 0.9.600
+      
+      # add software dependencies here
+
+      # To publish to Netlify, RStudio Connect, or GitHub Pages, uncomment
+      # the appropriate block below
+      
+      # - name: Publish to Netlify (and render)
+      #   uses: quarto-dev/quarto-actions/publish@v2
+      #   with:
+      #     to: netlify
+      #     NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        
+      # - name: Publish to RStudio Connect (and render)
+      #   uses: quarto-dev/quarto-actions/publish@v2
+      #   with:
+      #     to: connect
+      #     CONNECT_SERVER: enter-the-server-url-here
+      #     CONNECT_API_KEY: ${{ secrets.CONNECT_API_KEY }} 
+
+      # - name: Publish to GitHub Pages (and render)
+      #   uses: quarto-dev/quarto-actions/publish@v2
+      #   with:
+      #     to: gh-pages
+      #   env:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions
+