diff --git a/README.md b/README.md index e118027..49346c8 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # isc-proposal + This repository is a boilerplate repository that helps you prepare your proposal for the [R Consortium](https://www.r-consortium.org). @@ -47,13 +50,26 @@ This is a boilerplate repository that you will need to fork, title appropriately - Solicit feedback and contributions from others ### Automatically generate your proposal -You can configure this to produce the needed documents and publish them to the github.io for browsing and posterity. This assumes a reasonable amount of comfort with using Travis-CI but if you're not, please check out my [post on auto-deploying documents](http://itsalocke.com/automated-documentation-hosting-on-github-via-travis-ci/) for background. + +#### Using Travis CI (paid) + +You can configure this to produce the needed documents and publish them to the github.io for browsing and posterity. This assumes a reasonable amount of comfort with using Travis-CI but if you're not, please check out Steph Locke's [post on auto-deploying documents](http://itsalocke.com/automated-documentation-hosting-on-github-via-travis-ci/) for background. - Turn on [Travis-CI](https://travis-ci.org) for the repository - Add an environment variable called GH_TOKEN to the travis environment, set the value to an OAuth key generated by github to allow "public repo" privileges only - Amend the `.push_gh_pages.sh` and `ghgenerate.R` with the details of your repository and preferred commit details - Use the gh-pages branch to host your proposal online and to retrieve the HTML or PDF variants for emailing +#### Using GitHub Actions (free) + +You can also deploy your proposal without the need for Travis using the included GitHub workflow. This process is very similar to the above, and can be done in with the following steps: + +- Create an access token in your GitHub settings (Settings > Developer Settings > Personal Access Tokens > Tokens (classic)). Give this token the `public_repo` permissions, and copy the key. +- Add the access token to your repository as a secret (In the repository, go to Settings > Secrets and Variables > Actions > Repository Secrets). The action assumes you will call this `GH_SECRET_TOKEN`, but you can name it anything you want. +- Move the `github_action_deployment.yml` file to `.github/workflows/github_action_deployment.yml`. Ensure that line 13 matches what you called your repository secret. +- amend the first three lines of `ghgenerate.R` with the details of your repository / proposal + +Now whenever you push to `main`, it should automatically trigger a deployment of your proposal. No action is needed to change values in `.push_gh_pages.sh`, but you should still change the values in the first three lines of `ghgenerate.R`. ## License Creative Commons Licence
ISC Boilerplate by Stephanie Locke is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at https://github.com/RConsortium/isc-proposal. diff --git a/github_action_deployment.yml b/github_action_deployment.yml new file mode 100644 index 0000000..dc15683 --- /dev/null +++ b/github_action_deployment.yml @@ -0,0 +1,70 @@ +name: Build and deploy + +## Place this in .github/workflows to run on push to main +## Ensure that workflows have write access in Settings > Actions > General > Workflow Permissions > Read and write permissions +## Also make sure that the name of your access token is correct (L13) -- here it's saved as "GH_SECRET_TOKEN" + +on: + push: + branches: + - main +env: + cache-version: v1 + GITHUB_PAT: ${{ secrets.GH_SECRET_TOKEN }} # make sure this matches the name of your github secret + +jobs: + build: + runs-on: ubuntu-latest + container: r-base:latest + env: + R_REMOTES_NO_ERRORS_FROM_WARNINGS: true + steps: + - name: Install pandoc + uses: r-lib/actions/setup-pandoc@v2 + + - name: Install dependencies with apt + run: | + apt-get update + apt-get install -y texlive-latex-base texlive-fonts-extra git lmodern texlive-latex-recommended rsync + + - name: Restore cached R packages + if: runner.os != 'Windows' # probably unneccessary but included just in case + uses: actions/cache/restore@v4 + with: + path: /usr/local/lib/R/site-library + restore-keys: ${{ env.cache-version }}-${{ runner.os }}-r- + + # timeout is increased because I'm having failures from downloads timing out + # shouldn't be a big deal--installs are cached so it only happens once (ideally) + - name: Install dependencies with CRAN + run: | + options(timeout = max(1000, getOption("timeout"))) + options(repos = c(CRAN = "https://cran.r-project.org")) + install.packages(c("knitr", "rmarkdown")) + write.csv(installed.packages()[,c(1,3)], file="./depends.csv") + shell: Rscript {0} + + # This sometimes fails, but it doesn't really matter -- failure just means nothing to change. + - name: Cache R packages + if: runner.os != 'Windows' # see L31 + uses: actions/cache/save@v4 + with: + path: /usr/local/lib/R/site-library + key: ${{ env.cache-version }}-${{ runner.os }}-r-${{ hashFiles('./depends.csv') }} + + - name: checkout + uses: actions/checkout@v4 + + # gh-pages will look for an index.html file, so just copy the static file to that name + - name: build + run: | + mkdir docs + Rscript ghgenerate.R + cp out/isc-proposal.html out/index.html + + - name: Deploy 🚀 + uses: JamesIves/github-pages-deploy-action@releases/v4 + with: + token: ${{ env.GITHUB_PAT }} + branch: gh-pages # The branch the action should deploy to. + folder: out # The folder the action should deploy. ghgenerate.R automatically puts these files in `out`.