improve api documentation syntax highlighting

refs CNVS-26515 Switch to the prettify library and highlight not just json but html, xml, and bash. test plan: `rake doc:api` and open up the generated docs. throughout the docs, code should be syntax highlighted, including stuff like curl commands and xml that weren't highlighted before. It should be easier to copy/paste this code now, without a weird hidden text box appearing. Change-Id: Icd33159836826e144cb14b96187cb8c645559885 Reviewed-on: https://gerrit.instructure.com/70345 Reviewed-by: Brad Humphrey <[email protected]> Tested-by: Jenkins Product-Review: Brian Palmer <[email protected]> QA-Review: Brian Palmer <[email protected]>
Timvandervoord · Jan 15, 2016 · 3390bfa · 3390bfa
1 parent 0a4e162
commit 3390bfa
Show file tree

Hide file tree

Showing 20 changed files with 803 additions and 805 deletions.
diff --git a/doc/api/README.md b/doc/api/README.md
@@ -25,11 +25,15 @@ POST and PUT requests may also optionally be sent in <a href="http://www.json.or
 
 As an example, this HTML form request:
 
-    name=test+name&file_ids[]=1&file_ids[]=2&sub[name]=foo&sub[message]=bar
+```bash
+name=test+name&file_ids[]=1&file_ids[]=2&sub[name]=foo&sub[message]=bar
+```
 
 would translate into this JSON request:
 
-    { "name": "test name", "file_ids": [1,2], "sub": { "name": "foo", "message": "bar" } }
+```json
+{ "name": "test name", "file_ids": [1,2], "sub": { "name": "foo", "message": "bar" } }
+```
 
 With either encoding, all timestamps are sent and returned in ISO 8601 format (UTC time zone):
 
@@ -44,11 +48,15 @@ query string or POST parameters is also supported.
 
 OAuth2 Token sent in header:
 
-    curl -H "Authorization: Bearer <ACCESS-TOKEN>" https://canvas.instructure.com/api/v1/courses
+```bash
+curl -H "Authorization: Bearer <ACCESS-TOKEN>" "https://canvas.instructure.com/api/v1/courses"
+```
 
 OAuth2 Token sent in query string:
 
-    curl https://canvas.instructure.com/api/v1/courses?access_token=<ACCESS-TOKEN>
+```bash
+curl "https://canvas.instructure.com/api/v1/courses?access_token=<ACCESS-TOKEN>"
+```
 
 Read more about <a href="oauth.html">OAuth2 and how to get access tokens.</a>
 
@@ -73,5 +81,6 @@ itself. You can generate this documentation yourself if you've set up a
 local Canvas environment following the instructions on <a href="https://www.github.com/instructure/canvas-lms/wiki">Github</a>,
 run the following command from your Canvas directory:
 
-    bundle exec rake doc:api
-
+```bash
+bundle exec rake doc:api
+```
diff --git a/doc/api/assignment_tools.md b/doc/api/assignment_tools.md
@@ -4,43 +4,43 @@ Grade Passback Tools
 Graded external tools are configured just like regular external tools. The
 difference is that rather than adding the tool to a course as a link in a
 module, a navigation item, etc. the tool gets added as an assignment.
-Instructors will see a new assignment type called "External Tool" where 
+Instructors will see a new assignment type called "External Tool" where
 they can select a tool configuration to use for the assignment. When students
 go to view the assignment instead of seeing a standard Canvas description
-they'll see the tool loaded in an iframe on the page. The tool can then 
+they'll see the tool loaded in an iframe on the page. The tool can then
 send grading information back to Canvas.
 
 Tools can know that they have been launched in a graded context because
 an additional parameter is sent across, `lis_outcome_service_url`,
-as specified in the LTI 1.1 specification. Grades are passed back to Canvas 
-from the tool's servers using the 
-<a href="http://www.imsglobal.org/LTI/v1p1/ltiIMGv1p1.html#_Toc319560472">outcomes component of LTI 1.1</a>. 
+as specified in the LTI 1.1 specification. Grades are passed back to Canvas
+from the tool's servers using the
+<a href="http://www.imsglobal.org/LTI/v1p1/ltiIMGv1p1.html#_Toc319560472">outcomes component of LTI 1.1</a>.
 
 ## Data Return Extension
 
 Canvas sends an extension parameter for assignment launches that allows the tool
-provider to pass back values as submission text in canvas. 
-The key is `ext_outcome_data_values_accepted` and the value is a comma separated list of 
+provider to pass back values as submission text in canvas.
+The key is `ext_outcome_data_values_accepted` and the value is a comma separated list of
 types of data accepted. The currently available data types are `url` and `text`.
-So the added launch parameter will look like this: 
+So the added launch parameter will look like this:
 
 `ext_outcome_data_values_accepted=url,text`
 
 ### Returning Data Values from Tool Provider
- 
+
 If the external tool wants to supply these values, it can augment the POX sent
 with the grading value. <a href="http://www.imsglobal.org/LTI/v1p1/ltiIMGv1p1.html#_Toc319560473">LTI replaceResult POX</a>
 
-Only one type of resultData should be sent, if multiple types are sent the tool 
-consumer behavior is undefined and is implementation-specific. Canvas will take 
+Only one type of resultData should be sent, if multiple types are sent the tool
+consumer behavior is undefined and is implementation-specific. Canvas will take
 the text value and ignore the url value if both are sent.
 
 ####Text
 
-Add a `resultData` node with a `text` node of plain text in the same encoding as 
+Add a `resultData` node with a `text` node of plain text in the same encoding as
 the rest of the document within it like this:
 
-<pre>
+```xml
 <?xml version = "1.0" encoding = "UTF-8"?>
 <imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
   <imsx_POXHeader>
@@ -69,13 +69,13 @@ the rest of the document within it like this:
     </replaceResultRequest>
   </imsx_POXBody>
 </imsx_POXEnvelopeRequest>
-</pre>
+```
 
 ####URL
 
 Add a `resultData` node with a `url` node within it like this:
 
-<pre>
+```xml
 <?xml version = "1.0" encoding = "UTF-8"?>
 <imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
   <imsx_POXHeader>
@@ -104,7 +104,7 @@ Add a `resultData` node with a `url` node within it like this:
     </replaceResultRequest>
   </imsx_POXBody>
 </imsx_POXEnvelopeRequest>
-</pre>
+```
 
 
 ## Total Score Return Extension
@@ -125,7 +125,7 @@ Simply add a node called `resultTotalScore` instead of `resultScore`. If both ar
 sent, then `resultScore` will be ignored. The `textString` value  should be
 an Integer or Float value.
 
-<pre>
+```xml
 <?xml version = "1.0" encoding = "UTF-8"?>
 <imsx_POXEnvelopeRequest xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
   <imsx_POXHeader>
@@ -151,4 +151,4 @@ an Integer or Float value.
     </replaceResultRequest>
   </imsx_POXBody>
 </imsx_POXEnvelopeRequest>
-</pre>
+```
diff --git a/doc/api/compound_documents.md b/doc/api/compound_documents.md
@@ -30,8 +30,10 @@ Secondary collections should never be considered as ordered or complete.
 
 Example:
 
-    {
-      "meta": {"primaryCollection": "comments"},
-      "comments": [...],
-      "authors": [...]
-    }
+```json
+{
+  "meta": {"primaryCollection": "comments"},
+  "comments": [...],
+  "authors": [...]
+}
+```
diff --git a/doc/api/endpoint_attributes.md b/doc/api/endpoint_attributes.md
@@ -11,10 +11,11 @@ For example, consider an assignment description containing a link to a wiki page
 the same course.  The description returned by the Get Assignment API might look
 like this:
 
-    !!!javascript
-    <a href="http://canvas.example.com/courses/123/pages/a-wiki-page"
-       data-api-endpoint="http://canvas.example.com/api/v1/courses/123/pages/a-wiki-page"
-       data-api-returntype="Page">More information here</a>
+```html
+<a href="http://canvas.example.com/courses/123/pages/a-wiki-page"
+   data-api-endpoint="http://canvas.example.com/api/v1/courses/123/pages/a-wiki-page"
+   data-api-returntype="Page">More information here</a>
+```
 
 The currently supported `data-api-returntype` values are:
 

diff --git a/doc/api/file_uploads.md b/doc/api/file_uploads.md
@@ -42,28 +42,31 @@ Arguments:
 
 Example Request:
 
-    curl 'https://<canvas>/api/v1/users/self/files' \
-         -F 'name=profile_pic.jpg' \
-         -F 'size=302185' \
-         -F 'content_type=image/jpeg' \
-         -F 'parent_folder_path=my_files/section1' \
-         -H "Authorization: Bearer <token>"
+```bash
+curl 'https://<canvas>/api/v1/users/self/files' \
+     -F 'name=profile_pic.jpg' \
+     -F 'size=302185' \
+     -F 'content_type=image/jpeg' \
+     -F 'parent_folder_path=my_files/section1' \
+     -H "Authorization: Bearer <token>"
+```
 
 Example Response:
 
-    !!!javascript
-    {
-      "upload_url": "https://some-bucket.s3.amazonaws.com/",
-      "upload_params": {
-        "key": "/users/1234/files/profile_pic.jpg",
-        "acl": "private",
-        "Filename": "profile_pic.jpg",
-        "AWSAccessKeyId": "some_id",
-        "Policy": "some_opaque_string",
-        "Signature": "another_opaque_string",
-        "Content-Type": "image/jpeg"
-      }
-    }
+```json
+{
+  "upload_url": "https://some-bucket.s3.amazonaws.com/",
+  "upload_params": {
+    "key": "/users/1234/files/profile_pic.jpg",
+    "acl": "private",
+    "Filename": "profile_pic.jpg",
+    "AWSAccessKeyId": "some_id",
+    "Policy": "some_opaque_string",
+    "Signature": "another_opaque_string",
+    "Content-Type": "image/jpeg"
+  }
+}
+```
 
 At this point, the file object has been created in Canvas in a "pending"
 state, with no content. It will not appear in any listings in the UI until
@@ -91,16 +94,18 @@ last parameter following all the others.
 
 Example Request:
 
-    curl '<upload_url>' \ 
-         -F 'key=/users/1234/files/profile_pic.jpg' \ 
-         -F 'acl=private' \ 
-         -F 'Filename=profile_pic.jpg' \ 
-         -F 'AWSAccessKeyId=some_id' \ 
-         -F 'Policy=some_opaque_string' \ 
-         -F 'Signature=another_opaque_string' \ 
-         -F 'Content-Type=image/jpeg' \ 
-         -F '<any other fields returned in upload_params>' \
-         -F 'file=@my_local_file.jpg'
+```bash
+curl '<upload_url>' \
+     -F 'key=/users/1234/files/profile_pic.jpg' \
+     -F 'acl=private' \
+     -F 'Filename=profile_pic.jpg' \
+     -F 'AWSAccessKeyId=some_id' \
+     -F 'Policy=some_opaque_string' \
+     -F 'Signature=another_opaque_string' \
+     -F 'Content-Type=image/jpeg' \
+     -F '<any other fields returned in upload_params>' \
+     -F 'file=@my_local_file.jpg'
+```
 
 The access token is not sent with this request.
 
@@ -130,20 +135,23 @@ authentication.
 
 Example Request:
 
-    curl -X POST '<Location>' \
-         -H 'Content-Length: 0' \
-         -H "Authorization: Bearer <token>"
+```bash
+curl -X POST '<Location>' \
+     -H 'Content-Length: 0' \
+     -H "Authorization: Bearer <token>"
+```
 
 Example Response:
 
-    !!!javascript
-    {
-      'id': 1234,
-      'url': '...url to download the file...',
-      'content-type': 'image/jpeg',
-      'display_name': 'profile_pic.jpg',
-      'size': 302185
-    }
+```json
+{
+  "id": 1234,
+  "url": "...url to download the file...",
+  "content-type": "image/jpeg",
+  "display_name": "profile_pic.jpg",
+  "size": 302185
+}
+```
 
 <h2 class='api_method_name' name='method.file_uploads.url' data-subtopic="Uploading Files">
 <a name="method.file_uploads.url" href="#method.file_uploads.url">Uploading via URL</a>
@@ -167,22 +175,25 @@ with the addition of one new parameter:
 
 Example Request:
 
-    curl 'https://<canvas>/api/v1/users/self/files' \
-         -F 'url=http://example.com/my_pic.jpg' \
-         -F 'name=profile_pic.jpg' \
-         -F 'size=302185' \
-         -F 'content_type=image/jpeg' \
-         -F 'parent_folder_path=my_files/section1' \
-         -H "Authorization: Bearer <token>"
+```bash
+curl 'https://<canvas>/api/v1/users/self/files' \
+     -F 'url=http://example.com/my_pic.jpg' \
+     -F 'name=profile_pic.jpg' \
+     -F 'size=302185' \
+     -F 'content_type=image/jpeg' \
+     -F 'parent_folder_path=my_files/section1' \
+     -H "Authorization: Bearer <token>"
+```
 
 Example Response:
 
-    !!!javascript
-    {
-      'id': 1234,
-      'upload_status': 'pending',
-      'status_url' '...url to check status...'
-    }
+```json
+{
+  "id": 1234,
+  "upload_status": "pending",
+  "status_url": "...url to check status..."
+}
+```
 
 Canvas will return a status_url parameter, which is a Canvas
 API endpoint that the application can periodically poll to check on the
@@ -196,35 +207,40 @@ the status_url.
 
 Example Request:
 
-    curl 'https://<canvas>/api/v1/files/1234/5678/status' \
-         -H "Authorization: Bearer <token>"
+```bash
+curl 'https://<canvas>/api/v1/files/1234/5678/status' \
+     -H "Authorization: Bearer <token>"
+```
 
 When still pending:
 
-    !!!javascript
-    {
-      'upload_status': 'pending'
-    }
+```json
+{
+  "upload_status": "pending"
+}
+```
 
 When complete:
 
-    !!!javascript
-    {
-      'upload_status': 'ready',
-      // This is the normal attachment JSON response object
-      'attachment': {
-        'id': 1234,
-        'url': '...url to download the file...',
-        'content-type': 'image/jpeg',
-        'display_name': 'profile_pic.jpg',
-        'size': 302185
-      }
-    }
+```json
+{
+  "upload_status": "ready",
+  // This is the normal attachment JSON response object
+  "attachment": {
+    "id": 1234,
+    "url": "...url to download the file...",
+    "content-type": "image/jpeg",
+    "display_name": "profile_pic.jpg",
+    "size": 302185
+  }
+}
+```
 
 On error:
 
-    !!!javascript
-    {
-      'upload_status': 'errored',
-      'message': 'Invalid response code, expected 200 got 404'
-    }
+```json
+{
+  "upload_status": "errored",
+  "message": "Invalid response code, expected 200 got 404"
+}
+```