generated from jhudsl/OTTR_Template_Website
-
Notifications
You must be signed in to change notification settings - Fork 1
/
customize-robots.Rmd
156 lines (110 loc) · 7.78 KB
/
customize-robots.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
---
title: "Customizing Automatic Checks"
output:
html_document:
toc: true
toc_float: true
---
By default, all automation steps and checks will run. Based on the requirements of your course, you have the flexibility to enable or disable specific features by modifying the settings in the `config_automation.yml` file. Simply adjust the options to "yes" or "no" accordingly.
The `config_automation.yml` file looks like this:
```
##### Checks run at pull request #####
# Check quiz formatting
check-quizzes: no
# Check that urls in the content are not broken
url-checker: yes
# Render preview of content with changes (Rmd's and md's are checked)
render-preview: yes
# Spell check Rmds and quizzes
spell-check: yes
# Style any R code
style-code: yes
# Test build the docker image if any docker-relevant files have been changed
docker-test: no
# Should URLs be tested periodically?
url-check-periodically: yes
...
```
There are three main sets of automation steps and checks run:
- `.github/workflows/pull-request.yml` : Run upon opening a pull request
- `.github/workflows/render-all.yml`: Run upon any changes merged to the `main` branch
- `.github/workflows/check-url.yml`: Run checks of URLs in a OTTR repo periodically to see if any are no longer valid
## Pull Request Checks:
These actions are triggered upon a pull request being opened. They are set up in the file: `.github/workflows/pull-request.yml`/.
### Check Quiz Formatting
In the `config_automation.yml` file it is set by:
```
check-quizzes: no
```
By default, it is set to `no`. But if you wish to [create quizzes on Leanpub](https://github.com/jhudsl/OTTR_Template/wiki/Publishing-on-Leanpub), you should set this to `yes`. This is not necessary if you only want quizzes for Coursera.
Leanpub needs a particular format for it to upload correctly. This action will look for quizzes in the `quizzes` directory and check for these items. The outcome of these quiz checks will be printed to a GitHub comment on your pull request.
### Check for broken URLs
In the `config_automation.yml` file there are two different URL checkers.
1) One that is run during pull requests. It is set by:
```
url-checker: yes
```
GitHub Actions runs a check on all the URLs upon creating a pull request to the `main` branch.
If it fails, you can click on the output comment on your pull request that says "Download errors here". This will give you a print out of the broken URLs it found.
GitHub Actions runs a check on all the URLs upon creating a pull request to the `main` branch.
If it fails, you can click on the output comment on your pull request that says "Download errors here". This will give you a print out of the broken URLs it found.
2) The other URL check runs on a set interval to see if any URLs referenced are no longer valid. This one is set by:
```
url-check-periodically: yes
```
If either URL checker is failing on something that isn't really a URL or doesn't need to be checked, open the `resources/ignore-urls.txt` file and add that URL exactly as it is specified in the error print out.
### Preview rendering
In the `config_automation.yml` file it is set by:
```
render-preview: yes
```
After you open a pull request, a preview of the renders will be linked in an automatic comment on the pull request. Upon each commit these previews will re-render and edit the comment with the latest render.
These Github Actions are located in `render-preview` section of the `pull-request.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 checking
In the `config_automation.yml` file it is set by:
```
spell-check: yes
```
Github Actions will automatically run a spell check on all Rmds and mds whenever a pull request to the `main` branch is filed.
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. Errors will be printed out on a GitHub comment on your pull request.
To resolve those spelling errors, click on the link with the errors on the autogenerated comment.
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).
After committing the changes to `resources/dictionary.txt` on your branch, the spell check status check should be successfully passed.
### Style code
In the `config_automation.yml` file it is set by:
```
style-code: yes
```
The `styler` package will style R code in all Rmds. Style changes will automatically be committed back to your branch.
### Docker testing
In the config_automation.yml file it looks like:
```
docker-test: no
```
By default it is set to `no` which means it won't run automatically unless you change this to `yes`.
This is only relevant if you have [your own Docker image you are managing for your course](https://github.com/jhudsl/OTTR_Template/wiki/Using-Docker#starting-a-new-docker-image). If changes are made to Docker-relevant files: `Dockerfile`, `install_github.R`, or `github_package_list.tsv`, this will test re-build the Docker image. If it is successfully built, then it makes sense to merge it to `main` but the Docker Image will not be pushed to `Dockerhub` automatically. [Follow these instructions to push your Docker image to Dockerhub](https://github.com/jhudsl/OTTR_Template/wiki/Using-Docker#pushing-the-docker-image).
<br>
## Rendering actions
Upon merging changes to any `Rmd` or `assets/` folder to `main`, the course material will be automatically re-rendered.
By default, all rendering steps will be run. But depending on the needs of your course, you can turn these on and off by going to the `config_automation.yml` file and switching options to `yes` or `no`.
```
render-bookdown: yes
render-leanpub: yes
render-coursera: yes
```
For publishing to Leanpub, make sure that the render Leanpub option is set to yes: `render-leanpub: yes`. See more details about publishing to Leanpub [here](https://github.com/jhudsl/OTTR_Template/wiki/Publishing-on-Leanpub).
For publishing to Coursera, make sure render Coursera option is set to yes: `render-coursera: yes`. See more details about publishing to Coursera [here](https://github.com/jhudsl/OTTR_Template/wiki/Publishing-on-Coursera).
<br>
## Manually running rendering or checks
From time to time, it may be useful to manually re-trigger a particular GitHub Action. Most of the GitHub Actions, particularly the rendering ones, can be re-run manually. See this article about [how to manually re-run a GitHub Action](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow#running-a-workflow).
<br>
## Fixing broken GitHub Actions
GitHub action rendering or other GitHub actions may fail sometimes if the input is unexpected or for a number of other reasons.
To investigate why a GitHub action has failed, go to `Actions` and click on the failed action. [See this article for how to find this information](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions#viewing-the-workflows-activity).
See our [FAQ's section](./faqs.html) for the most commonly encountered errors and how to address them.
If you are unsure what the error message means and have trouble addressing it, please [file an issue on the OTTR_Template repository to get help](https://github.com/jhudsl/OTTR_Template/issues/new?assignees=cansavvy&labels=bug&template=course-template-problem-report.md).