How to set up and customize GitHub actions robots

Here's a summary of the Github actions set up in this repository.

Note: if you are not a part of jhudsl organization, you will need to set follow these instructions to set up your GitHub secrets before these actions will work.

In summary, here's what the GitHub actions do for you (when set up):

• Re-render Bookdown after merging to main
• Create a preview of the rendered version with changes you've made on a pull request
• Re convert files for Coursera
• Spell check
• Fix code styling
• Checks for broken URLs
• Copy over Leanpub-needed files to the Leanpub repository
• Re-render Leanpub files (on the other repository)
• Checks if Docker image changes successfully build
• Push changed Docker images to Dockerhub

Here's a diagram to summarize:

These Github actions also work across repositories to support converting Bookdown content into formats ready for publishing on Coursera or Leanpub.

If you are only looking to use this template for creating a Bookdown course, this diagram is not as pertinent.

Preview of render

After you open a pull request, a preview of the renders as they will appear after the pull request is accepted is run and linked to in a comment on the pull request. Upon each commit these previews will re-render and edit the comment with the time of the latest render. These Github Actions are located in render-preview.yml. These previews do NOT incorporate any changes influenced by any changes to the Docker image if the Dockerfile is also updated in the same pull request.

Spell check

Github actions will automatically run a spell check on all Rmds whenever a pull request to the main branch is filed. Depending on your preference, you may find it easier to spell check manually on your local computer before pushing to Github.

It will fail if there are more than 2 spelling errors and you'll need to resolve those before being able to merge your pull request.

To resolve those spelling errors, go to this repository's Actions tab. Then, click on the GitHub action from the PR you just submitted. Scroll all the way down to Artifacts and click spell-check-results. This will download a zip file with a TSV that lists all the spelling errors.

Some of these errors may be things that the spell check doesn't recognize for example: ITCR or DaSL. If it's a 'word' the spell check should recognize, you'll need to add this to the dictionary.

Go to the resources/dictionary.txt file. Open the file and add the new 'word' to its appropriate place (the words are in alphabetical order). Then commit the changes to resources/dictionary.txt to your branch and this should make the spell check status check pass.

Code styling

Github actions will run the styler package to all style R in all Rmds whenever a pull request to the main branch is filed. Style changes will automatically be committed back to your branch.

URL Checking

GitHub actions runs a check on all the URLs upon creating a pull request to the main branch. If it fails, you'll need to go the Actions tab of this repository, then find the GitHub check_urls job for the last commit you just pushed. Click on check_urls and the specific step of Check URLs to see a print out of the URLs tested.

If the URL checker is failing on something that isn't really a URL or doesn't need to be checked, open up the GitHub actions file: .github/workflows/url-checker.yml and add the imposter URL on to the exclude-urls: argument with a comma in between.

Customizing render-bookdown.yml

If you plan on doing a lot of customizing with GitHub actions or would like to become more familiar, we recommend reading this article to get your feet wet. Then this reference guide in the GitHub actions docs is super useful.

Note that build-all and docker-build-test are not something we recommend requiring for status checks because docker-build-test is only run if there are changes to the Dockerfile and build-all is only run upon the acceptance and merging of a pull request.

However for simplicity purposes there are two sections this Github action that can you keep off if you won't be making changes to the Docker image or you won't be wanting it to sync to Google Slides automatically.

For a course that needs to publish to the Leanpub repository

transfer-rendered-files.yml is a Github action that will copy over the output docs/ files rendered by Bookdown to a parallel Leanpub repository.

Once build-all is run, the docs/ folder where the rendered files are place are copied over to the Leanpub repository and filed as a pull request.

There are two edits to .github/workflow/transfer-rendered-files.yml that need to be done to turn on the automatic copying of files between these repos:

1. Change line 28 to the repository name you would like the docs/ files to be transferred to.

repository: jhudsl/Course_Template_Quizzes

2. Uncomment lines 13-18 in this file:

# Only run after the render finishes running
#workflow_run:
#  workflows: [ "Build, Render, and Push" ]
#  branches: [ main ]
#  types:
#    - completed

For a course that needs to publish to Coursera

The render-bookdown.yml github action the chapter content for Coursera by using this command within the docker image:

leanbuild::render_coursera()

You can run this same command locally if you wish to test something. This render the chapters without the table of Contents. If you do not wish to publish to Coursera and prefer this do not run, you may delete this section (but it shouldn't hurt anything to keep as is -- unless for some reason it causes you some troubles).

Additionally, the Leanpub companion repository has a Leanpub -> Coursera quiz conversion script if you choose to create quizzes and publish on both Leanpub and Coursera.