diff --git a/README.md b/README.md
index 58e1a69a9c69983f784c25c009fa4b96ee14a653..6006736e20f89d1c65d2a138a507f97bec23604d 100644
--- a/README.md
+++ b/README.md
@@ -1,33 +1,28 @@
-# Online course starter: Python
+# Online course documentation
-This is a starter repo based on the
-[course framework](https://github.com/ines/spacy-course) I developed for my
-[spaCy course](https://course.spacy.io). The front-end is powered by
-[Gatsby](http://gatsbyjs.org/) and [Reveal.js](https://revealjs.com) and the
-back-end code execution uses [Binder](https://mybinder.org) đź’–
-
-[](https://app.netlify.com/start/deploy?repository=https://github.com/ines/courser-starter-python)
-
-[](https://course-starter-python.netlify.com)
+The following documentation is for the LiU online course ETE335. This is repo is based on the
+[Spacy course framework](https://github.com/ines/spacy-course). However, several additions have been made to the original repository to meet the needs of our course.
-## đź“– Documentation
+There exists some unused code from the orginal course starter. Work is being done to remove this.
-<a href="https://ines.github.io/course-starter-python/"><img width="300" src="https://user-images.githubusercontent.com/13643239/75773176-ab897a00-5d4d-11ea-8593-1fc018885611.png" align="right"></a>
+Work is also being done to collect all course specific features (course information, faq, static images, etc.) into a single directory.
-Thanks to [@hfboyce](https://github.com/hfboyce) for contributing a super detailed guide on getting started with this course framework, adding exercises, slides and other content, and customizing the design. It also comes with a Dockerfile that takes care of the dependencies for you.
+The front-end is powered by
+[Gatsby](http://gatsbyjs.org/) and [Reveal.js](https://revealjs.com) and the
+back-end code execution uses [Binder](https://mybinder.org).
-[➡️ **Read the documentation here**](https://ines.github.io/course-starter-python/)
+[The documentation for the original course framework can be found here.](https://ines.github.io/course-starter-python/)
## âś… Quickstart
1. [Import](https://github.com/new/import) this repo, install it and make sure
the app is running locally.
-2. Customize the [`meta.json`](meta.json) and
- [`binder/requirements.txt`](binder/requirements.txt).
-3. Build a [Binder](https://mybinder.org) from the `binder` branch of this repo.
-4. Add content (chapters, exercises and slides) and optionally add separate
- content license.
+2. Create a separate repository for your binder-container. Build a [Binder](https://mybinder.org) from that repo. [The binder repo used for this course can be found here](https://github.com/oskarholmstrom/binder_nlp_course).
+3. Customize the following files with course specific information:
+ - [`meta.json`](meta.json)
+ -
+4. Add content (chapters, exercises and slides) in the tasks and exercises directories.
5. Customize the UI theme in [`theme.sass`](theme.sass) and update images in
[`static`](static) as needed.
6. Deploy the app, e.g. to [Netlify](https://netlify.com).
@@ -41,7 +36,7 @@ and then all other dependencies. This should serve up the app on
```bash
npm install -g gatsby-cli # Install Gatsby globally
npm install # Install dependencies
-npm run dev # Run the development server
+gatsby develop --https # Run the development server
```
## 🎨 Customization
@@ -54,10 +49,11 @@ customization are available:
| ------------------------- | ------------------------------------------------------ |
| `meta.json` | General config settings, title, description etc. |
| `theme.sass` | Color theme. |
-| `binder/requirements.txt` | Python requirements to install. |
-| `chapters` | The chapters, one Markdown file per chapter. |
+| `tasks` | The chapters, one Markdown file per chapter. |
| `slides` | The slides, one Markdown file per slide deck. |
| `static` | Static assets like images, will be copied to the root. |
+| `exercises` | The exercises that are loaded into a codeblock |
+
### `meta.json`
@@ -72,16 +68,16 @@ Gatsby to see the changes if you're editing it while the server is running.**
| `description` | Course description. Used for site meta and in footer. |
| `bio` | Author bio. Used in the footer. |
| `siteUrl` | URL of the deployed site (without trailing slash). |
-| `twitter` | Author twitter handle, used in Twitter cards meta. |
+| `twitter` | *NOT USED* Author twitter handle, used in Twitter cards meta. |
| `fonts` | [Google Fonts](https://fonts.google.com) to load. Should be the font part of the URL in the embed string, e.g. `Lato:400,400i,700,700i`. |
| `testTemplate` | Template used to validate the answers. `${solution}` will be replaced with the user code and `${test}` with the contents of the test file. |
-| `juniper.repo` | Repo to build on Binder in `user/repo` format. Usually the same as this repo. |
-| `juniper.branch` | Branch to build. Ideally not `master`, so the image is not rebuilt every time you push. |
+| `juniper.repo` | Repo to build on Binder in `user/repo` format. |
+| `juniper.branch` | Branch to build. (Should be master/main for GitHub/GitLab) |
| `juniper.lang` | Code language for syntax highlighting. |
| `juniper.kernelType` | The name of the kernel to use. |
| `juniper.debug` | Logs additional debugging info to the console. |
-| `showProfileImage` | Whether to show the profile image in the footer. If `true`, a file `static/profile.jpg` needs to be available. |
-| `footerLinks` | List of objects with `"text"` and `"url"` to display as links in the footer. |
+| `showProfileImage` | *NOT USED* Whether to show the profile image in the footer. If `true`, a file `static/profile.jpg` needs to be available. |
+| `footerLinks` | *NOT USED* List of objects with `"text"` and `"url"` to display as links in the footer. |
| `theme` | Currently only used for the progressive web app, e.g. as the theme color on mobile. For the UI theme, edit `theme.sass`. |
### Static assets
@@ -92,98 +88,137 @@ The following assets need to be available and can be customized:
| File | Description |
| ----------------- | -------------------------------------------------------- |
-| `icon.png` | Custom [favicon](https://en.wikipedia.org/wiki/Favicon). |
+| `faviicon.png` | Custom [favicon](https://en.wikipedia.org/wiki/Favicon). |
| `logo.svg` | The course logo. |
-| `profile.jpg` | Photo or profile image. |
-| `social.jpg` | Social image, displayed in Twitter and Facebook cards. |
+| `[name]_square` | Photo or profile image (jpg or png). |
| `icon_check.svg` | "Check" icon displayed on "Mark as completed" button. |
| `icon_slides.svg` | Icon displayed in the corner of a slides exercise. |
## ✏️ Content
-### File formats
+The course content consists of chapters and their tasks (sub-chapters). The tasks consists of data and exercises.
-#### Chapters
+# Task Creation and Info
-Chapters are placed in [`/chapters`](/chapters) and are Markdown files
-consisting of `<exercise>` components. They'll be turned into pages, e.g.
-`/chapter1`. In their frontmatter block at the top of the file, they need to
-specify `type: chapter`, as well as the following meta:
+Both chapters and tasks share similar metadata values.
-```yaml
----
-title: The chapter title
-description: The chapter description
-prev: /chapter1 # exact path to previous chapter or null to not show a link
-next: /chapter3 # exact path to next chapter or null to not show a link
-id: 2 # unique identifier for chapter
-type: chapter # important: this creates a standalone page from the chapter
----
+Chapter meta-data:
+- title: The title of the task/chapter (string).
+- description: A description of the task (string, optional).
+- type: The type of the document, i.e. chapter.
+- next: The name of the file for the next chapter, e.g. kapitel_4.
+- prev: The name of the file for the previous chapter, e.g. kapitel_3.
+- id: An autogenerated globally unique ID.
+- index: The chapter's index. (Will be automatically generated from a separate list of chapters)
+
+Task meta-data:
+- title: The title of the task/chapter (string).
+- description: A description of the task (string, optional).
+- type: The type of the document, i.e. task.
+- location: The name of the file for the chapter that the task belongs to.
+- chapter_id: The id for the chapter that the task belongs to.
+- next: The name of the file for the next task, e.g. deluppgift_2.
+- prev: The name of the file for the previous chapter, e.g. deluppgift_1.
+- id: An autogenerated globally unique ID (string)
+- index: The task's index. (Will be automatically generated from a separate list of tasks)
+
+
+Exercises have metadata added to its tag. Example:
+```jsx
+<exercise id="4e536d87-84d6-40ae-9b06-408d79f2a726" title="NLP 1">
```
-#### Slides
+Exercise meta-data:
+- id: A generated globally unique id (string).
+- title: Exercise title (string).
+- skipcomplete: Added as a single argument (See example below). This is used for exercises where the student should not be able to mark the exercise as completed. (The exercise can only be completed through successfully solving the exercise.)
+- type: Optional type. `"slides"` makes container wider and adds icon. (string)
-Slides are placed in [`/slides`](/slides) and are markdown files consisting of
-slide content, separated by `---`. They need to specify the following
-frontmatter block at the top of the file:
+```jsx
+<exercise skipcomplete id="2dadcd46-ef83-469c-8483-8f4254b8123e" title="Slutför analogin">
+```
-```yaml
----
-type: slides
----
+## How to create a chapter:
+Run generate_chapter.py to create a chapter. Enter the chapter title
+
+## How to create a task:
+Run generate_task.py to create a task. Firstly, enter the chapter title the task should belong to, then title of the task to be created.
+
+## How to create a exercise:
+Exercises must have a unique id generated by generate_id.py. Run generate_id.py and copy the id.
+Example:
+```jsx
+<exercise id="4e536d87-84d6-40ae-9b06-408d79f2a726" title="NLP 1">
```
-The **first and last slide** use a special layout and will display the headline
-in the center of the slide. **Speaker notes** (in this case, the script) can be
-added at the end of a slide, prefixed by `Notes:`. They'll then be shown on the
-right next to the slides. Here's an example slides file:
-```markdown
----
-type: slides
----
+## Exercise sub-components
-# Processing pipelines
+Sub-components can be added inside the tags of an exercise. Example:
-Notes: This is a slide deck about processing pipelines.
+```jsx
+<exercise id="9cc35895-2bbf-4f01-be7c-b1ff6a700aab" title="Ordinbäddningar">
----
+<video url="https://web.microsoftstream.com/embed/video/f103f420-cfe5-47e0-92f6-cf91b403800c">
+</video>
-# Next slide
+</exercise>
+```
-- Some bullet points here
-- And another bullet point
+**(Note: It is important that leading and closing tags are on separate rows, and that there are at least one new line between sub-components and the exercise tag.)**
-<img src="/image.jpg" alt="An image located in /static" />
+Following are the different sub-components that can be used in an exercise.
+
+### Presentation components
+
+#### `<video>`
+
+Container to display an embedded video.
+
+| Argument | Type | Description |
+| -------- | ------ | --------------------------------------------- |
+| `url` | string | An embedding link to a video. |
+
+```markdown
+<video url="https://web.microsoftstream.com/embed/video/f103f420-cfe5-47e0-92f6-cf91b403800c">
+</video>
```
-### Custom Elements
+#### `<slides>`
+
+(These are not used in ETE335, as the lectures are presented through video and the slides are available through PDF.)
+
+Container to display slides interactively using Reveal.js and a Markdown file.
+
+| Argument | Type | Description |
+| -------- | ------ | --------------------------------------------- |
+| `source` | string | Name of slides file (without file extension). |
+
+```markdown
+<slides source="chapter1_01_introduction-to-spacy">
+</slides>
+```
-When using custom elements, make sure to place a newline between the
-opening/closing tags and the children. Otherwise, Markdown content may not
-render correctly.
-#### `<exercise>`
+### Code components
-Container of a single exercise.
+#### `<<multi-codeblock>`
-| Argument | Type | Description |
-| ------------ | --------------- | -------------------------------------------------------------- |
-| `id` | number / string | Unique exercise ID within chapter. |
-| `title` | string | Exercise title. |
-| `type` | string | Optional type. `"slides"` makes container wider and adds icon. |
-| **children** | - | The contents of the exercise. |
+Multi-codeblocks contain codeblocks and should be used even if there is only a single codeblock. The component keeps track of information regarding the individual codeblocks (how many there are, how many have been correctly answered).
```markdown
-<exercise id="1" title="Introduction to spaCy">
-Content goes here...
+<multi-codeblock>
-</exercise>
+<codeblock data-executable id=1_1_01>
+</codeblock>
+
+</multi-codeblock>
```
+
#### `<codeblock>`
| Argument | Type | Description |
@@ -195,59 +230,223 @@ Content goes here...
| **children** | string | Optional hints displayed when the user clicks "Show hints". |
```markdown
-<codeblock id="02_03">
+<codeblock data-executable id=1_1_01>
This is a hint!
</codeblock>
```
-#### `<slides>`
-Container to display slides interactively using Reveal.js and a Markdown file.
+### Input types category
+Inputs are divided into match types and input types (default type), those are further divided into subcategories
+- Input-type: The simplest form of input, the only subcategory of this is **regex-input**
-| Argument | Type | Description |
-| -------- | ------ | --------------------------------------------- |
-| `source` | string | Name of slides file (without file extension). |
+**regex-input**
+| Prop | Type | Description | Optional |
+|--------|--------|--------------|----------|
+| regex | string | - | No |
-```markdown
-<slides source="chapter1_01_introduction-to-spacy">
-</slides>
+<br>
+Example:
+
+```jsx
+<regex-input regex="58\/63" id=3></regex-input>
+// Will compare the user answer to 58/63
```
-#### `<choice>`
+- Input-match: Wirriten in the form `<SubCategory><Match>`, these components come with their own submit button
+ and are used as a single answer exerciese. Match categories should not be children to `multi-answer`
-Container for multiple-choice question.
+<br>
+
+**regex-match** (similar to regex-input but comes with a button)
+
+| Prop | Type | Description | Optional |
+|--------|--------|--------------|----------|
+| regex | string | - | No |
+
+<br>
+
+**numeric-match**
+| Prop | Type | Description | Optional |
+|---------|--------|-------------------------------------------------| -------- |
+| correct | number | The right answer | No |
+| right | string | The message displayed when correctly answered | Yes |
+| wrong | string | The message displayed when incorrectly answered | Yes |
+
+<br>
+
+**range-match** Numerical range input Both ends **exclusicve**
+| Prop | Type | Description | Optional |
+|---------|--------|-------------------------------------------------| -------- |
+| from | number | The first correct number in the range | No |
+| to | number | The last correct number in the range | No |
+| right | string | The message displayed when correctly answered | Yes |
+| wrong | string | The message displayed when incorrectly answered | Yes |
+
+
+<br>
+
+**exact-match**
+| Prop | Type | Description | Optional |
+|---------|--------|-------------------------------------------------| -------- |
+| correct | string | The right answer | No |
+| right | string | The message displayed when correctly answered | Yes |
+| wrong | string | The message displayed when incorrectly answered | Yes |
+
+
+<br>
+
+Examples
+```jsx
+<exact-match correct="fönster" right="Bra jobbat!" wrong="Fel svar"/>
+
+<numeric-match correct=10 right="Bra jobbat!" wrong="Fel svar"/>
+
+<range-match from=10 to=15 right="This right because it's and arithmetic range" wrong="Fel svar"/>
+```
+---
+### Choice types category
+The use chooses one of the answers, this category is divided into multiple subcategories based
+on the answer, e.g, multiple correct answers, one correct answer, one correct answer(different UI)
+All of them use the opt tag as children which can idicate the correct answer.
+
+<br>
+
+**opt-tag**
+
+| Prop | Type | Description | Optional |
+|--------- |-----------------|--------------------------------------------------------------------| -------- |
+| text | string | The answer text shown to the user | No |
+| correct | boolean(string) | The message displayed when correctly answered ("true" or "false") | No |
+| children | text | The message displayeed when this option is picked | Yes |
+| answer | string | The message displayeed when this option is picked | Yes |
+
+
+<br>
+
+**select-choice**
+
+| Prop | Type | Description | Optional |
+|----------|----------|-------------------------------------------------------------------------| -------- |
+| children | opt-tags | The options provided for the user. | No |
+| right | string | The message displayed when correctly answered. | Yes |
+| wrong | string | The message displayed when incorrectly answered. | Yes |
+
+
+<br>
+
+**multi-choice** Multiple correct answers, the options are provided with the opt tag.
+
+| Prop | Type | Description | Optional |
+|----------|----------|-------------------------------------------------------------------------| -------- |
+| partial | string | The message dispalyed when only some of the correct answers are picked. | No |
+| right | string | The message displayed when correctly answered. | Yes |
+| wrong | string | The message displayed when incorrectly answered. | Yes |
+| children | opt-tags | The options provided for the user. | No |
+
+<br>
+
+**choice** Almost exactly like multichoice but only one opt-tag child can be declared as correct.
+
+| Prop | Type | Description | Optional |
+|----------|----------|-------------------------------------------------------------------------| -------- |
+| right | string | The message displayed when correctly answered. | Yes |
+| wrong | string | The message displayed when incorrectly answered. | Yes |
+| children | opt-tags | The options provided for the user. | No |
+
+<br>
+
+Examples:
+
+```jsx
+<multichoice right="Fint!" partial="Nästan rätt." wrong="Inte rätt alls.">
+
+<opt text="Answer one" correct="true" answer="This is not the correct answer.">
+</opt>
+
+<opt text="Answer two" correct="true" answer="Good job!">
+</opt>
+
+<opt text="Answer three" answer="This is not correct either.">
+</opt>
+
+</multichoice>
-| Argument | Type | Description |
-| ------------ | --------------- | -------------------------------------------------------------------------------------------- |
-| `id` | string / number | Optional unique ID. Can be used if more than one choice question is present in one exercise. |
-| **children** | nodes | Only `<opt>` components for the options. |
-```markdown
<choice>
-<opt text="Option one">You have selected option one! This is not good.</opt>
-<opt text="Option two" correct="true">Yay! </opt>
+<opt text="Answer one" answer="This is not the correct answer.">
+</opt>
+
+<opt text="Answer two" correct="true" answer="Good job!">
+</opt>
+
+<opt text="Answer three" answer="This is not correct either.">
+</opt>
</choice>
+
+
+<select-choice>
+
+<opt text="aaaaaa">
+</opt>
+
+<opt text="bbbbb" correct="true">
+</opt>
+
+<opt text="ccccc">
+</opt>
+
+</select-choice>
```
-#### `<opt>`
-A multiple-choice option.
+### Slides
+
+Slides are placed in [`/slides`](/slides) and are markdown files consisting of
+slide content, separated by `---`. They need to specify the following
+frontmatter block at the top of the file:
+
+```yaml
+---
+type: slides
+---
+
+```
+
+The **first and last slide** use a special layout and will display the headline
+in the center of the slide. **Speaker notes** (in this case, the script) can be
+added at the end of a slide, prefixed by `Notes:`. They'll then be shown on the
+right next to the slides. Here's an example slides file:
+
+```markdown
+---
+type: slides
+---
+
+# Processing pipelines
+
+Notes: This is a slide deck about processing pipelines.
+
+---
+
+# Next slide
+
+- Some bullet points here
+- And another bullet point
+
+<img src="/image.jpg" alt="An image located in /static" />
+```
-| Argument | Type | Description |
-| ------------ | ------ | ---------------------------------------------------------------------------------------------- |
-| `text` | string | The option text to be displayed. Supports inline HTML. |
-| `correct` | string | `"true"` if the option is the correct answer. |
-| **children** | string | The text to be displayed if the option is selected (explaining why it's correct or incorrect). |
### Setting up Binder
-The [`requirements.txt`](binder/requirements.txt) in the repository defines the
-packages that are installed when building it with Binder. You can specify the
-binder settings like repo, branch and kernel type in the `"juniper"` section of
+You need to create a public repository that setups the container that the students will access.
+[The binder repo used for this course can be found here](https://github.com/oskarholmstrom/binder_nlp_course).
+You can specify the binder settings like repo, branch and kernel type in the `"juniper"` section of
the `meta.json`. I'd recommend running the very first build via the interface on
the [Binder website](https://mybinder.org), as this gives you a detailed build
log and feedback on whether everything worked as expected. Enter your repository
@@ -256,6 +455,15 @@ image.
+When you update your binder repository, redo the process on the [Binder website](https://mybinder.org).
+
+All files in the binder repository can be accessed by the users through the code cells. If there is code that should be run, and that the users should not see, it is best to include the code as a binary.
+
+It is necessary to include a **requirements.txt** file. The file should contain all external libraries that should be installed on the binder container.
+
+The **postBuild** file will run after packages have been installed. It is especially useful if large datasets (larger than what can be stored on GitHub for example) should be downloaded.
+
+
### Adding tests
To validate the code when the user hits "Submit", we're currently using a
@@ -307,8 +515,3 @@ def test():
The string answer is available as `__solution__`, and the test also has access
to the solution code.
-
----
-
-For more details on how it all works behind the scenes, see
-[the original course repo](https://github.com/ines/spacy-course).
diff --git a/binder/requirements.txt b/binder/requirements.txt
deleted file mode 100644
index 112cf2449007956231e52f04d5c8b0b0100ed926..0000000000000000000000000000000000000000
--- a/binder/requirements.txt
+++ /dev/null
@@ -1 +0,0 @@
-wasabi>=0.2.1,<1.1.0
diff --git a/docs/img/chapter_layout.png b/docs/img/chapter_layout.png
deleted file mode 100644
index 5cd82329a856d8a188efd1e80ee029b641c344ee..0000000000000000000000000000000000000000
Binary files a/docs/img/chapter_layout.png and /dev/null differ
diff --git a/docs/img/chapters_img.png b/docs/img/chapters_img.png
deleted file mode 100644
index d0087dbede0157b206a7fd54d9e9098c0641eeac..0000000000000000000000000000000000000000
Binary files a/docs/img/chapters_img.png and /dev/null differ
diff --git a/docs/img/julia.png b/docs/img/julia.png
deleted file mode 100644
index 106ce78e1d2f81d61374a583be18185b56d2bc96..0000000000000000000000000000000000000000
Binary files a/docs/img/julia.png and /dev/null differ
diff --git a/docs/img/multi-q-exercise.png b/docs/img/multi-q-exercise.png
deleted file mode 100644
index 5cf1e95ebf9c8bdacaf4c0d14e96134499966ed4..0000000000000000000000000000000000000000
Binary files a/docs/img/multi-q-exercise.png and /dev/null differ
diff --git a/docs/img/naome.png b/docs/img/naome.png
deleted file mode 100644
index 6c52784f672561474c8e97c34f34bc681aa1bdfe..0000000000000000000000000000000000000000
Binary files a/docs/img/naome.png and /dev/null differ
diff --git a/docs/task/task.md b/docs/task/task.md
index 74cb97f3590d1aee17d69015d620a90093fc17df..36dcc8b2d2079c82b0be896acb11842b13176709 100644
--- a/docs/task/task.md
+++ b/docs/task/task.md
@@ -116,7 +116,7 @@ All of them use the opt tag as children which can idicate the correct answer.
|--------- |-----------------|--------------------------------------------------------------------| -------- |
| text | string | The answer text shown to the user | No |
| correct | boolean(string) | The message displayed when correctly answered ("true" or "false") | No |
-| children | text | The message displayeed when this option is picked | Yes |
+| answer | string | The message displayeed when this option is picked | Yes |
<br>
diff --git a/exercises/bookquotes.json b/exercises/bookquotes.json
deleted file mode 100644
index 3971080dc9258b0fb42326d3779c5794a372b695..0000000000000000000000000000000000000000
--- a/exercises/bookquotes.json
+++ /dev/null
@@ -1,26 +0,0 @@
-[
- [
- "One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.",
- { "author": "Franz Kafka", "book": "Metamorphosis" }
- ],
- [
- "I know not all that may be coming, but be it what it will, I'll go to it laughing.",
- { "author": "Herman Melville", "book": "Moby-Dick or, The Whale" }
- ],
- [
- "It was the best of times, it was the worst of times.",
- { "author": "Charles Dickens", "book": "A Tale of Two Cities" }
- ],
- [
- "The only people for me are the mad ones, the ones who are mad to live, mad to talk, mad to be saved, desirous of everything at the same time, the ones who never yawn or say a commonplace thing, but burn, burn, burn like fabulous yellow roman candles exploding like spiders across the stars.",
- { "author": "Jack Kerouac", "book": "On the Road" }
- ],
- [
- "It was a bright cold day in April, and the clocks were striking thirteen.",
- { "author": "George Orwell", "book": "1984" }
- ],
- [
- "Nowadays people know the price of everything and the value of nothing.",
- { "author": "Oscar Wilde", "book": "The Picture Of Dorian Gray" }
- ]
-]