github-to-canvas 0.1.0 → 0.1.1

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: cae13e5551446c7306ce3d8d90a12fa47a3caedbcebdc749b1852456b558c695
4
- data.tar.gz: 2501db731b91ab03fafae8a42eeaed104228cab7f5dcffaf21723558e9ac03f3
3
+ metadata.gz: a091b1eff741a97c405fa521cdc476c674f0d3dedb915d919045fab6244b5037
4
+ data.tar.gz: 5c384485dfcbb6da42dcf8db87115173d72b1ef548d3bfe99cfe6fec3af9ce98
5
5
  SHA512:
6
- metadata.gz: daf5758513ab73925cb7b7f402112ead3e9c0b3bcb4a59d6f227d5eb04ab710c7c9ecf06d3edf9326172d5758a8625a158e508f6eb68e740f8c5efd8cf31bc31
7
- data.tar.gz: 38cf70d8025eed5b8128e7885bb21ac9c8a25b94c89a0bd2fb00df7421ecc80df02615c26e335cb86bdce16d1d5653898617332a31249ce0478050b5a89f3818
6
+ metadata.gz: 5ae4d1c9c1ade17a0a15d148267f2e9c5949857c3f76ce0a65c1a0f6ac5e7c382ab29c2ae1ef9c37ace078178a7ae8a342e3f543813384d350279093cd483233
7
+ data.tar.gz: b2165b3675bc12d80149975edeaf77341ccade1687b1558a4463613853df78362c16f3520f1ae5baf394854cb06f4e21e1c90525feefeecccbd2103b684f712d
data/README.md CHANGED
@@ -4,19 +4,15 @@
4
4
 
5
5
  The `github-to-canvas` gem is designed to aid in integrating GitHub and the
6
6
  Canvas LMS. This gem takes a GitHub repository's `README.md` file, converts it
7
- to HTML, and pushes it to Canvas using the Canvas API. The gem also has the ability
8
- to updates a repository to include a `.canvas` file containing Canvas specific
9
- information.
10
-
11
- With the `.canvas` file in place, this gem can be used to continuously align
12
- content between GitHub and Canvas using the GitHub repository as the single
13
- source of truth.
7
+ to HTML, and pushes it to Canvas using the Canvas API. This gem can also update
8
+ existing Canvas lessons, allowing continuous alignment of content between GitHub
9
+ and Canvas, using the GitHub repository as the single source of truth.
14
10
 
15
11
  This gem is built for use internally at [Flatiron School][], so some features may be
16
12
  specific to Flatiron School branding and needs. Access to the
17
13
  [Canvas LMS API][] and the ability to add pages and assignments to a Canvas
18
14
  course are required. Write access to the GitHub repository being converted is
19
- also required for committing `.canvas` files.
15
+ also required for some features.
20
16
 
21
17
  ## Installation
22
18
 
@@ -47,7 +43,7 @@ echo "$(export 'CANVAS_API_KEY=your-new-API-key-here' | cat - ~/.bash_profile)"
47
43
 
48
44
  ### Add Canvas API Base Path
49
45
 
50
- The exact Canvas API path is specific to where you Canvas LMS is located. For example,
46
+ The exact Canvas API path is specific to where your Canvas LMS is located. For example,
51
47
  Flatiron School's base path is `https://learning.flatironschool.com/api/v1`. Add this path
52
48
  as an `ENV` variable like the API key. **Do not add a `/` at the end after `/api/v1`.**
53
49
 
@@ -65,67 +61,339 @@ After both the API key and path are added to `~/.zshrc`, run `source ~/.zshrc` (
65
61
  to make them available in your current terminal. You can verify these variables
66
62
  are present by running `ENV` and finding them in the output list.
67
63
 
68
- ## Usage
64
+ ## Common Uses
65
+
66
+ ### Creating and Updating Canvas Lessons
67
+
68
+ Relevant options:
69
+
70
+ - `--create-lesson`, `-c`: Requires a Canvas course ID. Creates a new Canvas
71
+ lesson, converting the local repository's README.md to HTML. Adds `.canvas`
72
+ file to remote repository
73
+ - `--align`, `-a`: Updates a canvas lesson based on the local repository's
74
+ README.md. If no other options are used, `--align` will look for a `.canvas`
75
+ file to know what to lesson to update
76
+ - `--course`: Provide a specific course ID. When used with `--id`, this can
77
+ override the default behavior for `--align`, allowing you to update any
78
+ existing lesson and ignore the `.canvas` file if present.
79
+ - `--id`: Provide a specific lesson ID. This can be found in the URL of the
80
+ specific lesson. For Pages, used the slugified lesson title.
81
+ - `--type`: Sets the type of Canvas lesson to be created (page, assignment or
82
+ discussion). If no type, type decided based on repository structure.
83
+ - `--name`: Can be used to override default naming behavior. By default, Canvas
84
+ lesson names are determined by the first top-level (`#`) header in the
85
+ repository's markdown file.
86
+ - `--fis-links`, `-l`: Adds additional Flatiron School HTML header after
87
+ markdown conversion, including links back to the GitHub repo and it's issue
88
+ form.
89
+ - `--forkable`: Adds a **Fork** button to the Flatiron School HTML header. For
90
+ use with custom Canvas JS to enable Canvas assignment forking workflow for
91
+ Flatiron School students.
92
+ - `--remove-header-and-footer`, `-r`: Removes top lesson header and any Flatiron
93
+ School specific footer links before converting to HTML. Removing top lesson
94
+ header prevent duplicate titles while viewing in Canvas.
95
+ - `--create-from-github`: Requires a GitHub repository URL. Also requires
96
+ `--course` and `--type`. Creates a Canvas lesson, reading from the remote repo
97
+ instead of a local repository. Repository must be public.
98
+ - `--align-from-github`: Requires a GitHub repo URL, `--course`, `--id`, and
99
+ `--type`. Updates a Canvas lesson from a remote repository.
100
+ - `--read-from-github`: Requires a GitHub repo URL. Reads a remote repository
101
+ and converts its contents to HTML, but does not push to Canvas.
102
+
103
+ #### Create a Canvas Lesson from a Local Repository
104
+
105
+ Navigate into a repository folder cloned down to your local machine and run:
106
+
107
+ ```sh
108
+ github-to-canvas -c <CANVAS_COURSE_ID> -lr --forkable
109
+ ```
110
+
111
+ The command above will create a Canvas lesson in the course provided. It will
112
+ also remove the repositories top-level header and remove any old Flatiron
113
+ branded footers. It will also add an HTML header for Canvas that includes links
114
+ back to the repository.
115
+
116
+ If the lesson type is an assignment, a Fork button will also be added to the
117
+ HTML header. Because the command didn't specify, the type of lesson is
118
+ determined based on the structure of the local repo - if it has sub-folders, the
119
+ lesson will become an assignment; if there are no sub-folders, the lesson will
120
+ become a page. If the lesson type is a page, the `--forkable` option will be
121
+ ignored.
122
+
123
+ Creating a lesson this way will also produce a `.canvas` file. This file
124
+ contains info about the Canvas lesson that was created.
125
+
126
+ #### Create a Canvas Lesson from a Remote Repository
127
+
128
+ To create from a remote repo, run the following command:
129
+
130
+ ```sh
131
+ github-to-canvas --create-from-github <URL> --course <CANVAS_COURSE_ID> --type <TYPE> -lr --forkable
132
+ ```
133
+
134
+ This command will read a GitHub markdown based on the provided URL and create a
135
+ Canvas lesson based on it. We need to provide the Course ID and the type of
136
+ lesson (`page` or `assignment`) as type can't be determined automatically. We'll
137
+ also continue to use `-lr --forkable` like the previous command to set up the
138
+ lesson the same way as before.
139
+
140
+ The repository must be public in order to read the markdown file.
141
+
142
+ #### Read a Remote Repository as HTML
143
+
144
+ To read the contents of a remote repo:
145
+
146
+ ```sh
147
+ github-to-canvas --read-from-github <URL>
148
+ ```
149
+
150
+ This will produce an HTML conversion of the repository's markdwon. This HTML can
151
+ be directly pasted into Canvas' HTML editor if a manual process is needed.
152
+
153
+ #### Update a Canvas Lesson from a Local Repository
154
+
155
+ If you previously created a Canvas lesson from a local repository, you should
156
+ have a `.canvas` file present in the repo. If that file is present, you can run
157
+ the following command to automatically update that same Canvas lesson:
158
+
159
+ ```sh
160
+ github-to-canvas -a -lr --forkable
161
+ ```
162
+
163
+ If you don't have or want to use the `.canvas` file, you can also specify the
164
+ course ID and lesson ID:
165
+
166
+ ```sh
167
+ github-to-canvas -a --course <CANVAS_COURSE_ID> --id <CANVAS_LESSON_ID> -lr --forkable
168
+ ```
169
+
170
+ Canvas course and lesson IDs can be found in the URL.
171
+
172
+ #### Update a Canvas Lesson from a Remote Repository
173
+
174
+ You can update an existing Canvas course using a remote GitHub repository like so:
175
+
176
+ ```sh
177
+ github-to-canvas --align-from-github <URL> --course <COURSE_ID> --id <LESSON_ID> --type <TYPE> -lr --forkable
178
+ ```
179
+
180
+ This will read remote markdown using the provided URL and update a Canvas course
181
+ using the info provided. Type must match the existing lesson type.
182
+
183
+ ### Course Creation
184
+
185
+ This gem has the ability to create Canvas courses from scratch. These features
186
+ are still in development and may not work for all course designs. Quiz and
187
+ Discussion Topic lesson creation is still under development and will not work.
188
+
189
+ By providing a YAML file of the desired course structure, this gem can create a
190
+ course, add in modules, and populate those modules with pages and assignments.
191
+ The required YAML file must follow a specific structure. Using the steps below,
192
+ this gem can create the necessary YAML markup from existing Canvas courses.
193
+
194
+ #### Retrieve Canvas Course Information as YAML
195
+
196
+ To create YAML markup of an existing Canvas course, use the following:
197
+
198
+ ```sh
199
+ github-to-canvas --query <CANVAS_COURSE_ID>
200
+ ```
201
+
202
+ This command will use the Canvas API to read a course's information, including
203
+ its module and lesson structure and lesson URLs. YAML markup will be produced as a result. This
204
+ output can be directly saved to a file, which will make the next step a little
205
+ easier:
206
+
207
+ ```sh
208
+ github-to-canvas --query <CANVAS_COURSE_ID> > query_results.yml
209
+ ```
210
+
211
+ The output will look similar to this:
212
+
213
+ ```yml
214
+ ---
215
+ :name: The Course's Title
216
+ :id: 111
217
+ :modules:
218
+ - :id: 2020
219
+ :name: First Module's Name
220
+ :lessons:
221
+ - id: slugified-page-name
222
+ title: This is the Title Of The First Lesson, a Page
223
+ indent: 0
224
+ type: Page
225
+ html_url: https://learning.flatironschool.com/courses/111/modules/items/27001
226
+ page_url: slugified-page-name
227
+ url: https://learning.flatironschool.com/api/v1/courses/111/pages/slugified-page-name
228
+ published: false
229
+ repository: ''
230
+ - id: 333
231
+ title: This is the Title Of The Second Lesson, an Assignment
232
+ indent: 1
233
+ type: Assignment
234
+ html_url: https://learning.flatironschool.com/courses/111/modules/items/27002
235
+ page_url: ''
236
+ url: https://learning.flatironschool.com/api/v1/courses/111/assignments/333
237
+ published: false
238
+ repository: ''
239
+ - :id: 2021
240
+ :name: Second Module's Name
241
+ :lessons:
242
+ ```
243
+
244
+ The output YAML will not include associated GitHub repository information.
245
+
246
+ #### Map GitHub Repositories to a Canvas Course YAML
247
+
248
+ To associate repositories to an existing course YAML, the following command can be used:
249
+
250
+ ```sh
251
+ github-to-canvas --map <YAML_FILE>
252
+ ```
253
+
254
+ For this feature to work, all Canvas lessons must have the GitHub HTML header
255
+ that is added using `-l`. This header contains the necessary repo information.
256
+
257
+ Save the output YAML to another file if you want to use it for later course
258
+ creation. For example:
259
+
260
+ ```sh
261
+ github-to-canvas --map query_results.yml > course_structure.yml
262
+ ```
263
+
264
+ The resulting YAML file will contain course information, the module and lesson
265
+ structure, and each lesson's associated GitHub repository.
266
+
267
+ #### Create New Canvas Course from YAML
268
+
269
+ To create a Canvas course with this gem, you will need a correctly structured
270
+ YAML file with the course info, modules, lessons and associated lesson
271
+ repositories. In addition, all lessons must have a type (`Page` or
272
+ `Assignment`), a repository, and a title. Other lesson options are currently
273
+ ignored.
274
+
275
+ With the necessary data configured, use the `--build-course` option and pass in
276
+ the course's YAML file:
277
+
278
+ ```sh
279
+ github-to-canvas --build-course course_structure.yml -lr --forkable
280
+ ```
281
+
282
+ This command will cause the following to happen:
69
283
 
70
- ### Create a Canvas Lesson
284
+ - Create a Canvas course using the top level `:name:` in the YAML data
285
+ - Create the first module
286
+ - Create the first lesson using the repository, title and type, as well as additional command options
287
+ - Add the newly created lesson to the current module
288
+ - Create the second lesson and add it to the module...
289
+ - Repeate process until all modules and lessons are created
71
290
 
72
- To create a Canvas lesson from a GitHub `README.md` file, at minimum, you will
73
- need to know the Canvas course id you are going to add to. This id can be found
74
- in the URL of the course.
291
+ #### Align an Existing Course from YAML
75
292
 
76
- Once you have the course id, you will need to do the following:
293
+ After you've created a course using the previous process, go through the
294
+ previous steps of `--query` and `--map` to get a fully updated YAML for your
295
+ newly created course.
77
296
 
78
- 1. Clone down the repository you'd like to push to Canvas.
79
- 2. Change directory into the new local repository
80
- 3. Run `github-to-canvas --create <your-course-id>` from inside the local repo
297
+ ```sh
298
+ github-to-canvas --query <COURSE_ID> > query_results.yml
299
+ github-to-canvas --map query_results.yml > your_new_course.yml
300
+ ```
301
+
302
+ With this data file, you can use the following command to update all lessons in
303
+ a course based on their GitHub repo:
304
+
305
+ ```sh
306
+ github-to-canvas --update-course YAML_FILE -lr --forkable
307
+ ```
81
308
 
82
- If everything is set up properly, `github-to-canvas` will create a Canvas lesson
83
- using `master` branch `README.md` and the name of the current folder. By
84
- default, if the repository contains folders, an **assignment** will be created.
85
- Otherwise, a **page** will be created.
309
+ The gem will iterate over the data and update every lesson according to the
310
+ associated repository.
86
311
 
87
- ### Saving `.canvas` to GitHub
312
+ ## Known Issues
88
313
 
89
- Using `--save-to-github` will create a `.canvas` YAML file in the local repo and attempt to commit
90
- and push it to the remote repository. This file contains the course id, the newly
91
- created page id, and the Canvas URL to the lesson for future reference.
314
+ ### HTML Code Snippets Do Not Render
315
+
316
+ The Canvas API renders all HTML it receives. If your repository's markdown
317
+ includes HTML that is not meant to be rendered (i.e. lessons on HTML or
318
+ JavaScript that include HTML code snippets), the content will be rendered as
319
+ part of the page's HTML, resulting in unusual display errors in Canvas.
320
+
321
+ To fix any rendering issues in Canvas, go to the Canvas WYSIWYG editor for the
322
+ afflicted lesson. Click the HTML editor option (`</>` button in the lower right) to
323
+ switch to HTML.
324
+
325
+ Read the GitHub repo as HTML:
326
+
327
+ ```sh
328
+ github-to-canvas --read-from-github URL
329
+ ```
92
330
 
93
- If you create multiple Canvas lessons from the same repository, each lesson's
94
- Canvas data will be stored in the `.canvas` file.
331
+ Copy the output HTML and paste it in to the Canvas editor. This should clear up
332
+ some larger page rendering issues, but may not fix all code snippets issues. To
333
+ fix these, switch back to the regular Canvas WYSIWYG editor, then open a second
334
+ tab to the GitHub repo you're converting from. Copy any HTML code snippets from
335
+ GitHub and paste them into the Canvas editor where they should be displayed.
95
336
 
96
- ### Update an Existing Canvas Lesson
337
+ The Canvas editor will treat the pasted HTML content as code and will
338
+ automatically replace some characters, escaping the code from the
339
+ normal rendering process.
97
340
 
98
- To update an existing Canvas lesson using a local repository, **a `.canvas` file
99
- must be present in the repo**, as it contains the lesson information for the
100
- Canvas API.
341
+ Note that realigning after fixing this content with the gem will break the
342
+ rendering for these lessons again. A fix is planned for this issue, but has not
343
+ been implemented.
101
344
 
102
- 1. Clone down and/or change directory into the repository you'd like to update
103
- 2. Run `github-to-canvas --align` from inside the local repo
345
+ ### Multi-Line Code Snippets Render as a Single Line
104
346
 
105
- `github-to-canvas` will get the course id and page/assignment id from the
106
- `.canvas` file and update the associated Canvas lesson. If there are multiple
107
- Canvas lessons included in the `.canvas` file, each lesson will be updated (i.e.
108
- you have the same lesson in two courses created from one repository).
347
+ The Github to Canvas gem uses an existing gem, Redcarpet, to handle the Markdown to HTML
348
+ conversion. This gem does not currently support multi-line codeblocks. This
349
+ functionality has been added in the Github to Canvas gem through monkeypatching.
350
+ This error should be resolved, but if you encounter code snippet rendering
351
+ issues, please open a new issue with a markdown example to replicate the error.
109
352
 
110
- ### Options
353
+ ### Markdown Formatting Issues Cause Errors in Canvas
111
354
 
112
- This gem provides to the following options:
355
+ Individual markdown headers, paragraphs and code snippets should be separated by
356
+ an empty line in the markdown. Without these empty lines, the contents will be
357
+ interpretted as one continuous paragraph and ignore formatting.
113
358
 
114
- * `-c, --create-lesson COURSE` - Creates a new Canvas lesson, converting the local repository's README.md to HTML. Adds .canvas file to remote repository
115
- * `-a, --align` - Updates a canvas lesson based on the local repository's README.md
116
- * `-n, --name NAME` - Sets the name of the new Canvas lesson to be created. If no name is given, repository folder name is used
117
- * `-t, --type TYPE` - Sets the type of Canvas lesson to be created (page, assignment or discussion). If no type, type decided based on repository structure
118
- * `-f, --file FILE` - Looks for and uses a markdown file in the currentt folder as source for conversion. Default file is README.md
119
- * `-b, --branch BRANCH` - Sets the repository branch used for lesson creation
120
- * `-s, --save-to-github` - Creates a local .canvas file and attempts to commit and push it to the GitHub repository
121
- * `-l, --fis-links` - Adds additional Flatiron School HTML after markdown conversion
122
- * `-r, --remove-header-and-footer` - Removes top lesson header and any Learn.co specific footer links before converting to HTML
123
- * `-o, --only-content` - For align functionality only - updates the HTML content of a lesson without changing the name
124
- * `-h, --help` - Outputs examples commands and all options
125
-
359
+ ## Overview of GitHub to Canvas workflows
360
+
361
+ Using this gem, you can maintain Canvas courses in multiple ways - either by
362
+ creating and updating individual Canvas lessons or through the YAML file process.
363
+
364
+ At Flatiron School, we use the Canvas blueprint course feature. We use the
365
+ github-to-canvas gem to update the blueprint copy of lessons. These updates will
366
+ appear in future copies of the course, or can be synced down to existing course
367
+ copies.
368
+
369
+ ![github-to-canvas workflow chart](./images/github-to-canvas_workflow.png)
370
+
371
+ This can either be done with individual lessons or using a YAML files to keep
372
+ entire courses updated.
373
+
374
+ If you are using github-to-canvas in this way, changes should always be made on
375
+ the repository, not on Canvas. Any changes made only on Canvas will get
376
+ overwritten if the lesson is updated using the gem.
377
+
378
+ ## Additional Options
379
+
380
+ ### Specify Branch
381
+
382
+ When creating or aligning content locally, you can use `--branch` (`-b`) to
383
+ specify which branch you want to use. If you have a newer repository with a
384
+ `main` branch instead of `master`, use this option.
385
+
386
+ If you are are creating or aligning content locally, the `.canvas` file is not
387
+ automatically committed to the repo. You can automatically commit this file by
388
+ including the `--save-to-github` (`-s`) option. This option will attempt to
389
+ commit and push the `.canvas` file to the remote repository.
390
+
391
+ Run `github-to-canvas --help` for additional options not listed in this Readme.
126
392
 
127
393
  ## Examples of Valid Images This Gem Can Convert
128
394
 
395
+ This gem can convert both standard inline markdown and HTML images.
396
+
129
397
  Inline Markdown:
130
398
 
131
399
  ![example in-line image](https://curriculum-content.s3.amazonaws.com/fewpjs/fewpjs-fetch-lab/Image_25_AsynchronousJavaScript.png)
@@ -142,10 +142,10 @@ OptionParser.new do |opts|
142
142
  "Creates a new Canvas lesson from a remote GitHub Readme. --course and --type options required") do |url|
143
143
  options[:create_from_github] = url
144
144
  end
145
- opts.on("--create-quiz-from-github GITHUB_URL",
146
- "Creates a new Canvas quiz from a remote GitHub YAML file. --course option required") do |url|
147
- options[:quiz_from_github] = url
148
- end
145
+ # opts.on("--create-quiz-from-github GITHUB_URL",
146
+ # "Creates a new Canvas quiz from a remote GitHub YAML file. --course option required") do |url|
147
+ # options[:quiz_from_github] = url
148
+ # end
149
149
  opts.on("--align-from-github GITHUB_URL",
150
150
  "Aligns an existing Canvas lesson using a remote GitHub Readme. --course, --id, and --type options required") do |url|
151
151
  options[:align_from_github] = url
@@ -1,4 +1,3 @@
1
- require 'byebug'
2
1
  require_relative './github-to-canvas/create_canvas_lesson'
3
2
  require_relative './github-to-canvas/update_canvas_lesson'
4
3
  require_relative './github-to-canvas/canvas_dotfile'
@@ -1,4 +1,3 @@
1
- require 'byebug'
2
1
  require 'json'
3
2
  require 'rest-client'
4
3
  require 'yaml'
@@ -74,7 +73,6 @@ class CanvasInterface
74
73
  }
75
74
  end
76
75
  begin
77
- byebug
78
76
  response = RestClient.post(url, payload, self.headers)
79
77
  rescue
80
78
  puts "Something went wrong while add lesson #{lesson_info["id"]} to module #{module_info["id"]} in course #{course_id}" if lesson_info["type"] == "Assignment"
@@ -1,4 +1,3 @@
1
- require 'byebug'
2
1
  require 'json'
3
2
  require 'rest-client'
4
3
  class GithubInterface
@@ -1,5 +1,4 @@
1
1
  require 'redcarpet'
2
- require 'byebug'
3
2
 
4
3
  class CustomRender < Redcarpet::Render::HTML
5
4
  def block_code(code, lang)
@@ -1,3 +1,3 @@
1
1
  class GithubToCanvas
2
- VERSION = "0.1.0"
2
+ VERSION = "0.1.1"
3
3
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: github-to-canvas
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.1.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - maxwellbenton