/
getting-started.Rmd
107 lines (75 loc) · 5.21 KB
/
getting-started.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
---
title: "getting-started"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{getting-started}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
# Intro to ottrpal
`ottrpal` contains tools and functions to be used with an [OTTR repository](https://github.com/jhudsl/OTTR_Template) course.
It converts an [OTTR course](https://github.com/jhudsl/OTTR_Template/wiki) (Open-Source Tools for Training Resources) into a files ready for upload to Massive Open Online Courses (MOOCs): [Coursera](https://www.coursera.org/) and [Leanpub](https://leanpub.com/).
- Go to the [main OTTR guide](https://github.com/jhudsl/OTTR_Template/wiki) for how to start creating courses with OTTR.
- [Read the ottrpal package documentation here](https://jhudatascience.org/ottrpal/docs/index.html).
## Installing ottrpal:
You can install `ottrpal` from CRAN or from GitHub.
## Optional input files:
- [a `Book.txt` file](https://leanpub.com/lfm/read#leanpub-auto-booktxt-sampletxt-and-manuscript-files) which lists the order of the chapters/quiz files (this can be autogenerated with `ottrpal`) (see [example file](https://github.com/jhudsl/OTTR_Template/blob/main/manuscript/Book.txt)).
- a directory containing quizzes in the form of `.md` files which have been written using the [Markua formatting specifications](https://leanpub.com/markua/read#leanpub-auto-quizzes-and-exercises) (see [example folder](https://github.com/jhudsl/OTTR_Quizzes/tree/main/quizzes)).
- A TSV file specifying `url`, `chapt_title`, `img_path` See this (https://github.com/jhudsl/OTTR_Template/blob/main/resources/chapt_screen_images/chapter_urls.tsv).
## Set up an OTTR GitHub repository
Follow the [instructions here](https://github.com/jhudsl/OTTR_Template/wiki/Start-a-new-course) to set up your own OTTR GitHub repository for a new course.
## Running ottrpal
In the base of your OTTR repository, you can run this command to set up a Leanpub version of your course.
The `ottrpal` package converts your files using this base function, where `base_url` is where the OTTR course pages are published, the GitHub pages URL.
```
ottrpal::bookdown_to_embed_leanpub(base_url = "https://jhudatascience.org/OTTR_Template/")
```
By default, `ottrpal` will re-run a `bookdown::render_book("index.Rmd")` rendering of your chapters first before converting the files to the Leanpub ready format.
However, if you wish to skip this step, you can set `render = FALSE` when running the `ottrpal::bookdown_to_embed_leanpub()` function.
## About the Book.txt file:
Leanpub requires a [`Book.txt`](https://leanpub.com/lfm/read#leanpub-auto-booktxt-sampletxt-and-manuscript-files) file to know what order the chapters/quizzes should be published.
By default, your `Book.txt` file will _not_ be autogenerated but `ottrpal` will look in your given directory for an existing `Book.txt` file which it will copy over to the output directory.
You can create a `Book.txt` file manually, or if your quizzes and chapters are numbered, `ottrpal` can create the `Book.txt` file based on the numbers going from low to high and quizzes following chapters of the same number.
(e.g. `quiz_03.md` will be placed after `03-some_chapter_file.Rmd`).
To have `ottrpal` attempt to autogenerate this file, set `make_book_txt` to `TRUE`.
```
ottrpal::bookdown_to_embed_leanpub(base_url = "https://jhudatascience.org/OTTR_Template/",
make_book_txt = TRUE)
```
If no `Book.txt` file is found and `make_book_txt` is set to `FALSE` (this is the default setting), `ottrpal` will fail.
A `ottrpal` autogenerated `Book.txt` file might look something like this:
```
index.Rmd
01-chapter.Rmd
quiz_1.md
02-chapter.Rmd
quiz_2.md
about.Rmd
```
Also note that any `index.Rmd` will always be placed first and any `about.Rmd` file will be placed last.
## Setting up quizzes:
By default, ottrpal will look for a folder called `quizzes/` to find your quiz `.md` files.
If your quizzes are located somewhere else, you will need to use the `quiz_dir` argument to specify that:
```
ottrpal::bookdown_to_embed_leanpub(base_url = "https://jhudatascience.org/OTTR_Template/",
make_book_txt = TRUE,
quiz_dir = "some_directory")
```
If you don't have quizzes, you can say `quiz_dir = NULL` to skip all quiz steps.
## About the output files
Leanpub's Github writing mode will look for a directory called `manuscript` to publish from.
You should not edit the files in `manuscript/` by hand since a re-run of `ottrpal` will cause your changes to be overwritten.
## Adding footer text:
If there is text you would like added to the end of each chapter (like a link to a feedback survey for example), you can supply a character string to the `footer_text` argument in the main `ottrpal::bookdown_to_leanpub()` function.
```
# Set up a character string
survey_link <- "Please provide any feedback you have by filing a GitHub issue [here](https://github.com/jhudsl/OTTR_Template/issues)"
# Supply the footer text in the main function
ottrpal::bookdown_to_embed_leanpub(base_url = "https://jhudatascience.org/OTTR_Template/",
make_book_txt = TRUE,
footer_text = survey_link)
```
```{r}
sessionInfo()
```