diff --git a/customize-robots.Rmd b/customize-robots.Rmd index ff78d21..cfd4e95 100644 --- a/customize-robots.Rmd +++ b/customize-robots.Rmd @@ -6,27 +6,50 @@ output: 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. +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 "true" or "false" accordingly. The `config_automation.yml` file looks like this: ``` +### Render preview of content with changes (Rmd's and md's are checked) +render-preview: true + ##### Checks run at pull request ##### # Check quiz formatting -check-quizzes: no +check-quizzes: false +quiz_error_min: 0 # 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 +url-checker: true +url_error_min: 0 # Spell check Rmds and quizzes -spell-check: yes +spell-check: true +spell_error_min: 0 + +#### Other options # Style any R code -style-code: yes +style-code: true +# Would you like your markdown files to be checked for formatting +markdown-linter: true +# Would you like a readability report on your markdowns? +readability-report: true # Test build the docker image if any docker-relevant files have been changed -docker-test: no +docker-test: false # Should URLs be tested periodically? -url-check-periodically: yes -... +url-check-periodically: true + +##### Renderings run upon merge to main branch ##### +# Rendering each platform's content +render-website: rmd +render-leanpub: true +render-coursera: true + +## Automate the creation of Book.txt file? yes/no +## This is only relevant if render-leanpub is yes, otherwise it will be ignored +make-book-txt: true + +# What docker image should be used for rendering? +# The default is jhudsl/base_ottr:main +rendering-docker-image: 'jhudsl/base_ottr:main' ``` There are three main sets of automation steps and checks run: @@ -44,10 +67,10 @@ These actions are triggered upon a pull request being opened. They are set up in In the `config_automation.yml` file it is set by: ``` -check-quizzes: no +check-quizzes: false ``` -By default, it is set to `no`. But if you wish to [create quizzes on Leanpub](https://www.ottrproject.org/course_publishing.html#publishing-with-leanpub), you should set this to `yes`. This is not necessary if you only want quizzes for Coursera. +By default, it is set to `false`. But if you wish to [create quizzes on Leanpub](https://www.ottrproject.org/course_publishing.html#publishing-with-leanpub), you should set this to `true`. 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 @@ -56,31 +79,34 @@ 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 +url-checker: true ``` 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. +If it fails, you can click on the output comment on your pull request that says "Click here to download detailed error reports". This will download a zip file containing a list 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. +It is necessary to set the error threshold in the config_automation file (see below); otherwise, the check summary may still report that the URL check failed, even if no errors were found. The error threshold controls how many errors are allowed before the check will fail. + +``` +url_error_min: 0 +``` 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 +url-check-periodically: true ``` -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. +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. After committing the changes to `resources/ignore-urls.txt` on your branch, the url check status check should be successfully passed. ### Preview rendering In the `config_automation.yml` file it is set by: ``` -render-preview: yes +render-preview: true ``` 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. -![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/screenshots/preview_comment.png) +![](https://raw.githubusercontent.com/ottrproject/ottrproject.github.io/main/resources/screenshots/preview_comment.png) 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. @@ -90,26 +116,37 @@ These previews do NOT incorporate any changes influenced by any changes to the D In the `config_automation.yml` file it is set by: ``` -spell-check: yes +spell-check: true ``` 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. +Just like the URL error threshold, the spelling error threshold option controls how many errors are allowed before the check will fail. -![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/screenshots/spell_check_comment.png) +``` +spell_error_min: 0 +``` + +In order to manage the accumulation of errors, we recommend resolving those or adjusting the threshold/allowable limit before merging your pull request. Errors are displayed in much the same way as URL check errors with a summary of how many errors are found. Click on the output comment on your pull request that says "Click here to download detailed error reports". This will download a zip file containing a list of the spelling errors it found. -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. +The pull request comment included below shows an example of a check that passed (spell check), and a check that failed (the URL check) with the option to download detailed error report(s). + +![](https://raw.githubusercontent.com/ottrproject/ottrproject.github.io/main/resources/screenshots/check_results.png) + +When all checks pass, the option to download error reports is no longer included, instead displaying a message that the URL and spell checks passed. + +![](https://raw.githubusercontent.com/ottrproject/ottrproject.github.io/main/resources/screenshots/check_results_pass.png) + ### Style code In the `config_automation.yml` file it is set by: ``` -style-code: yes +style-code: true ``` The `styler` package will style R code in all Rmds. Style changes will automatically be committed back to your branch. @@ -117,9 +154,9 @@ The `styler` package will style R code in all Rmds. Style changes will automatic In the config_automation.yml file it looks like: ``` -docker-test: no +docker-test: false ``` -By default it is set to `no` which means it won't run automatically unless you change this to `yes`. +By default it is set to `false` which means it won't run automatically unless you change this to `true`. This is only relevant if you have [your own Docker image you are managing for your course](https://www.ottrproject.org/customize-docker.html). 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://www.ottrproject.org/customize-docker.html#Testing_a_modified_Docker_image).
@@ -127,16 +164,38 @@ This is only relevant if you have [your own Docker image you are managing for yo ## 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`. + +For rendering a website version of the course (or your website), rather than `true` or `false`, the options are `rmd`, `rmd_web`, `quarto` or `quarto_web`. + +A course has chapters like a book, whereas a website version will appear more like a typical website. + + * If rendering a course with [R Markdown files](https://rmarkdown.rstudio.com/), use `rmd`. + * If rendering a course with [quarto files](https://quarto.org/), use `quarto`. + * If rendering a website with [R Markdown files](https://rmarkdown.rstudio.com/), use `rmd_web`. + * If rendering a website with [quarto files](https://quarto.org/), use `quarto_web`. + +``` +render-website: rmd +``` +### Rendering options for courses +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 `true` or `false`. + +``` +render-leanpub: true +render-coursera: true +``` + +For publishing to Leanpub, make sure that the render Leanpub option is set to true: `render-leanpub: true`. See more details about publishing to Leanpub [here](https://www.ottrproject.org/course_publishing.html#publishing-with-leanpub). + +If render-leanpub is true, the `make-book-txt` option is also relevant. This option controls whether you'd like to manually specify the order of your chapters and quizzes by creating the [Book.txt file](https://leanpub.com/lfm/read#leanpub-auto-the-booktxt-file) by hand or whether you'd like this to be [automatically generated based on file and quiz numbering.](https://ottrproject.org/ottrpal/#about-the-booktxt-file). Read more about this [in the upcoming section](https://www.ottrproject.org/examples.html#Setting_up_quizzes). + +By default, `make-book-txt: true` will use the numbering in the names of the documents for chapters and quizzes to order them, but if you'd like to specify the order for the chapters and quizzes to be different on Leanpub, then set this to `make-book-txt: false`, so as not to override the book.txt file that you would make manually. ``` -render-bookdown: yes -render-leanpub: yes -render-coursera: yes +make-book-txt: true ``` -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://www.ottrproject.org/course_publishing.html#publishing-with-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://www.ottrproject.org/course_publishing.html#publishing-with-coursera). +For publishing to Coursera, make sure render Coursera option is set to true: `render-coursera: true`. See more details about publishing to Coursera [here](https://www.ottrproject.org/course_publishing.html#publishing-with-coursera).
diff --git a/resources/screenshots/check_results.png b/resources/screenshots/check_results.png new file mode 100644 index 0000000..7855aac Binary files /dev/null and b/resources/screenshots/check_results.png differ diff --git a/resources/screenshots/check_results_pass.png b/resources/screenshots/check_results_pass.png new file mode 100644 index 0000000..4838cb0 Binary files /dev/null and b/resources/screenshots/check_results_pass.png differ diff --git a/resources/screenshots/preview_comment.png b/resources/screenshots/preview_comment.png new file mode 100644 index 0000000..de92767 Binary files /dev/null and b/resources/screenshots/preview_comment.png differ