documentation: putting things in perspective

[ijlyttle]

Even though (I think) I am reasonably "with it" :), it took me a while to build this mental model for quarto actions - I thought it could be useful for others.

My first exposure to actions is the {usethis} model, where you are provided a complete action that you can modify.

It took me a while to see the "building-block" model, where we compose our own actions. Given the flexibility of Quarto (R, Python, etc.), and the weird ways in which we will all use it, this makes sense.

I'd be happy to contribute a PR for the README that could have something like what's below.
I know it's a little wordy, and may be specific to my usage 🤓, but at least it can start a conversation.

Thanks!

---

Composing Quarto Actions

The actions described here (setup, render, publish) are meant to be used as building blocks in larger actions that you should feel confident to compose; we provide some examples.

The thing you'll make, an Action workflow, lives in a specific directory of your repository: .github/workflows, and is a YAML file (extension .yaml).
It has these main parts:

• trigger: under what conditions does this workflow run?
• defining the job:
  • runner: what platform to use?
  • setup: what does the runner need to install? Among other stuff, it will need to install quarto (using the setup action)
  • render: what should the runner do? If you have a quarto project, you'll use the quarto render action.
  • publish: once it has rendered, how (if?) to publish? There's a quarto action for that, too.

The trigger section is at the start of an action. If you wanted to run the action on every push to main (or master) or on every pull-request to main, you could do this:

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

You'll see this pattern a lot in the examples. If you like, you can run the action on a schedule.

Defining the job and the runner:

name: Render and Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:

This is the scaffolding for the rest of the steps. You'll likely want to run on unbuntu-latest because it is the least expensive (you'll hit the free limit later).

The first step is the setup. If using quarto, you'll always have something like this:

      - uses: actions/checkout@v2

      - uses: quarto-dev/quarto-actions/setup@v2

Now, you need to install "stuff", depending on what Quarto uses to render, e.g. R, Python, ...

From time to time, you might find that you have to specify a Linux library to be installed:

      - name: Install additional libraries on Linux
        if: runner.os == 'Linux'
        run: | 
          # adapt to your situation
          sudo apt-get update -y
          sudo apt-get install -y libcurl4-openssl-dev
          sudo apt-get install -y libharfbuzz-dev 
          sudo apt-get install -y libfribidi-dev

You'll know you need to do this if your action fails and the error says that you are missing a system library.

If you need a particular version of Python:

      - uses: actions/setup-python@v4
        with:
          python-version: 3.9.13
          cache: pip # caching pip dependencies

If you are using a Python virtual environment (not with renv):

      - run: pip install -r requirements.txt

If you are using R, you'll need to add the step to install

      - uses: r-lib/actions/setup-r@v2
        with:
          use-public-rspm: true

If you are using renv (which is likely if you are using R), you'll need this:

      - uses: r-lib/actions/setup-renv@v2

If you are using Python within renv, the setup-renv action will install your virtual environment - you don't need to do it explicitly.

Next, you may wish to render as a separate step so that you don't deploy on pull-resuests:

      - name: Render Quarto Project
        uses: quarto-dev/quarto-actions/render@v2

Finally, if you want to publish, for example, to GitHub pages:

      - name: Publish to GitHub Pages
        if: github.event_name != 'pull_request'
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          render: false
          target: gh-pages
          env:
            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions

[cscheid]

We go back and forth ourselves on how self-contained the quarto documentation for CI and publishing should be. The main issue is that there are many potential readers of that documentation with widely differing backgrounds, who will want different things.

To be totally honest, I wouldn't want to replace our documentation with your approach, and I'm not sure how to create different entry points that are easily navigable for folks with different backgrounds. This is a hard problem! Let me get back to you on that.

[ijlyttle]

No problem - I figured the best way to say something was to post it here. I agree that documentation is a hard problem; my purpose is only to share one perspective (as someone who likes pull-requests and who has been spoiled by {usethis}).

I leave it to you to close the issue or keep it open; I stand ready to help if/when you say so.

[cscheid]

It's a good document! We want to incorporate it as a separate page. Just need to figure out how to set it up.