{"id":13424050,"url":"https://github.com/ines/course-starter-python","last_synced_at":"2025-04-05T11:11:27.004Z","repository":{"id":98232059,"uuid":"182030405","full_name":"ines/course-starter-python","owner":"ines","description":"👩‍🏫🐍 Starter repo for building interactive Python courses","archived":false,"fork":false,"pushed_at":"2020-03-03T11:51:42.000Z","size":1653,"stargazers_count":506,"open_issues_count":19,"forks_count":118,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-29T10:09:33.010Z","etag":null,"topics":["binder","gatsby","gatsbyjs","jupyter","online-course","python"],"latest_commit_sha":null,"homepage":"https://course-starter-python.netlify.com","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ines.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-04-18T06:36:10.000Z","updated_at":"2025-03-26T17:40:20.000Z","dependencies_parsed_at":"2023-05-18T19:45:40.474Z","dependency_job_id":null,"html_url":"https://github.com/ines/course-starter-python","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ines%2Fcourse-starter-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ines%2Fcourse-starter-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ines%2Fcourse-starter-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ines%2Fcourse-starter-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ines","download_url":"https://codeload.github.com/ines/course-starter-python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325693,"owners_count":20920714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binder","gatsby","gatsbyjs","jupyter","online-course","python"],"created_at":"2024-07-31T00:00:47.520Z","updated_at":"2025-04-05T11:11:26.969Z","avatar_url":"https://github.com/ines.png","language":"CSS","readme":"# Online course starter: Python\n\nThis is a starter repo based on the\n[course framework](https://github.com/ines/spacy-course) I developed for my\n[spaCy course](https://course.spacy.io). The front-end is powered by\n[Gatsby](http://gatsbyjs.org/) and [Reveal.js](https://revealjs.com) and the\nback-end code execution uses [Binder](https://mybinder.org) 💖\n\n[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/ines/courser-starter-python)\n\n[![](https://user-images.githubusercontent.com/13643239/56341448-68fe9380-61b5-11e9-816f-5c71ae71b94f.png)](https://course-starter-python.netlify.com)\n\n## 📖 Documentation\n\n\u003ca href=\"https://ines.github.io/course-starter-python/\"\u003e\u003cimg width=\"300\" src=\"https://user-images.githubusercontent.com/13643239/75773176-ab897a00-5d4d-11ea-8593-1fc018885611.png\" align=\"right\"\u003e\u003c/a\u003e\n\nThanks 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.\n\n[➡️ **Read the documentation here**](https://ines.github.io/course-starter-python/) \n\n\n## ✅ Quickstart\n\n1. [Import](https://github.com/new/import) this repo, install it and make sure\n   the app is running locally.\n2. Customize the [`meta.json`](meta.json) and\n   [`binder/requirements.txt`](binder/requirements.txt).\n3. Build a [Binder](https://mybinder.org) from the `binder` branch of this repo.\n4. Add content (chapters, exercises and slides) and optionally add separate\n   content license.\n5. Customize the UI theme in [`theme.sass`](theme.sass) and update images in\n   [`static`](static) as needed.\n6. Deploy the app, e.g. to [Netlify](https://netlify.com).\n\n### Running the app\n\nTo start the local development server, install [Gatsby](https://gatsbyjs.org)\nand then all other dependencies. This should serve up the app on\n`localhost:8000`.\n\n```bash\nnpm install -g gatsby-cli  # Install Gatsby globally\nnpm install                # Install dependencies\nnpm run dev                # Run the development server\n```\n\n## 🎨 Customization\n\nThe app separates its source and content – so you usually shouldn't have to dig\ninto the JavaScript source to change things. The following points of\ncustomization are available:\n\n| Location                  | Description                                            |\n| ------------------------- | ------------------------------------------------------ |\n| `meta.json`               | General config settings, title, description etc.       |\n| `theme.sass`              | Color theme.                                           |\n| `binder/requirements.txt` | Python requirements to install.                        |\n| `chapters`                | The chapters, one Markdown file per chapter.           |\n| `slides`                  | The slides, one Markdown file per slide deck.          |\n| `static`                  | Static assets like images, will be copied to the root. |\n\n### `meta.json`\n\nThe following meta settings are available. **Note that you have to re-start\nGatsby to see the changes if you're editing it while the server is running.**\n\n| Setting              | Description                                                                                                                                |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| `courseId`           | Unique ID of the course. Will be used when saving completed exercises to the browser's local storage.                                      |\n| `title`              | The title of the course.                                                                                                                   |\n| `slogan`             | Course slogan, displayed in the page title on the front page.                                                                              |\n| `description`        | Course description. Used for site meta and in footer.                                                                                      |\n| `bio`                | Author bio. Used in the footer.                                                                                                            |\n| `siteUrl`            | URL of the deployed site (without trailing slash).                                                                                         |\n| `twitter`            | Author twitter handle, used in Twitter cards meta.                                                                                         |\n| `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`.   |\n| `testTemplate`       | Template used to validate the answers. `${solution}` will be replaced with the user code and `${test}` with the contents of the test file. |\n| `juniper.repo`       | Repo to build on Binder in `user/repo` format. Usually the same as this repo.                                                              |\n| `juniper.branch`     | Branch to build. Ideally not `master`, so the image is not rebuilt every time you push.                                                    |\n| `juniper.lang`       | Code language for syntax highlighting.                                                                                                     |\n| `juniper.kernelType` | The name of the kernel to use.                                                                                                             |\n| `juniper.debug`      | Logs additional debugging info to the console.                                                                                             |\n| `showProfileImage`   | Whether to show the profile image in the footer. If `true`, a file `static/profile.jpg` needs to be available.                             |\n| `footerLinks`        | List of objects with `\"text\"` and `\"url\"` to display as links in the footer.                                                               |\n| `theme`              | Currently only used for the progressive web app, e.g. as the theme color on mobile. For the UI theme, edit `theme.sass`.                   |\n\n### Static assets\n\nAll files added to `/static` will become available at the root of the deployed\nsite. So `/static/image.jpg` can be referenced in your course as `/image.jpg`.\nThe following assets need to be available and can be customized:\n\n| File              | Description                                              |\n| ----------------- | -------------------------------------------------------- |\n| `icon.png`        | Custom [favicon](https://en.wikipedia.org/wiki/Favicon). |\n| `logo.svg`        | The course logo.                                         |\n| `profile.jpg`     | Photo or profile image.                                  |\n| `social.jpg`      | Social image, displayed in Twitter and Facebook cards.   |\n| `icon_check.svg`  | \"Check\" icon displayed on \"Mark as completed\" button.    |\n| `icon_slides.svg` | Icon displayed in the corner of a slides exercise.       |\n\n## ✏️ Content\n\n### File formats\n\n#### Chapters\n\nChapters are placed in [`/chapters`](/chapters) and are Markdown files\nconsisting of `\u003cexercise\u003e` components. They'll be turned into pages, e.g.\n`/chapter1`. In their frontmatter block at the top of the file, they need to\nspecify `type: chapter`, as well as the following meta:\n\n```yaml\n---\ntitle: The chapter title\ndescription: The chapter description\nprev: /chapter1 # exact path to previous chapter or null to not show a link\nnext: /chapter3 # exact path to next chapter or null to not show a link\nid: 2 # unique identifier for chapter\ntype: chapter # important: this creates a standalone page from the chapter\n---\n\n```\n\n#### Slides\n\nSlides are placed in [`/slides`](/slides) and are markdown files consisting of\nslide content, separated by `---`. They need to specify the following\nfrontmatter block at the top of the file:\n\n```yaml\n---\ntype: slides\n---\n\n```\n\nThe **first and last slide** use a special layout and will display the headline\nin the center of the slide. **Speaker notes** (in this case, the script) can be\nadded at the end of a slide, prefixed by `Notes:`. They'll then be shown on the\nright next to the slides. Here's an example slides file:\n\n```markdown\n---\ntype: slides\n---\n\n# Processing pipelines\n\nNotes: This is a slide deck about processing pipelines.\n\n---\n\n# Next slide\n\n- Some bullet points here\n- And another bullet point\n\n\u003cimg src=\"/image.jpg\" alt=\"An image located in /static\" /\u003e\n```\n\n### Custom Elements\n\nWhen using custom elements, make sure to place a newline between the\nopening/closing tags and the children. Otherwise, Markdown content may not\nrender correctly.\n\n#### `\u003cexercise\u003e`\n\nContainer of a single exercise.\n\n| Argument     | Type            | Description                                                    |\n| ------------ | --------------- | -------------------------------------------------------------- |\n| `id`         | number / string | Unique exercise ID within chapter.                             |\n| `title`      | string          | Exercise title.                                                |\n| `type`       | string          | Optional type. `\"slides\"` makes container wider and adds icon. |\n| **children** | -               | The contents of the exercise.                                  |\n\n```markdown\n\u003cexercise id=\"1\" title=\"Introduction to spaCy\"\u003e\n\nContent goes here...\n\n\u003c/exercise\u003e\n```\n\n#### `\u003ccodeblock\u003e`\n\n| Argument     | Type            | Description                                                                                  |\n| ------------ | --------------- | -------------------------------------------------------------------------------------------- |\n| `id`         | number / string | Unique identifier of the code exercise.                                                      |\n| `source`     | string          | Name of the source file (without file extension). Defaults to `exc_${id}` if not set.        |\n| `solution`   | string          | Name of the solution file (without file extension). Defaults to `solution_${id}` if not set. |\n| `test`       | string          | Name of the test file (without file extension). Defaults to `test_${id}` if not set.         |\n| **children** | string          | Optional hints displayed when the user clicks \"Show hints\".                                  |\n\n```markdown\n\u003ccodeblock id=\"02_03\"\u003e\n\nThis is a hint!\n\n\u003c/codeblock\u003e\n```\n\n#### `\u003cslides\u003e`\n\nContainer to display slides interactively using Reveal.js and a Markdown file.\n\n| Argument | Type   | Description                                   |\n| -------- | ------ | --------------------------------------------- |\n| `source` | string | Name of slides file (without file extension). |\n\n```markdown\n\u003cslides source=\"chapter1_01_introduction-to-spacy\"\u003e\n\u003c/slides\u003e\n```\n\n#### `\u003cchoice\u003e`\n\nContainer for multiple-choice question.\n\n| Argument     | Type            | Description                                                                                  |\n| ------------ | --------------- | -------------------------------------------------------------------------------------------- |\n| `id`         | string / number | Optional unique ID. Can be used if more than one choice question is present in one exercise. |\n| **children** | nodes           | Only `\u003copt\u003e` components for the options.                                                     |\n\n```markdown\n\u003cchoice\u003e\n\n\u003copt text=\"Option one\"\u003eYou have selected option one! This is not good.\u003c/opt\u003e\n\u003copt text=\"Option two\" correct=\"true\"\u003eYay! \u003c/opt\u003e\n\n\u003c/choice\u003e\n```\n\n#### `\u003copt\u003e`\n\nA multiple-choice option.\n\n| Argument     | Type   | Description                                                                                    |\n| ------------ | ------ | ---------------------------------------------------------------------------------------------- |\n| `text`       | string | The option text to be displayed. Supports inline HTML.                                         |\n| `correct`    | string | `\"true\"` if the option is the correct answer.                                                  |\n| **children** | string | The text to be displayed if the option is selected (explaining why it's correct or incorrect). |\n\n### Setting up Binder\n\nThe [`requirements.txt`](binder/requirements.txt) in the repository defines the\npackages that are installed when building it with Binder. You can specify the\nbinder settings like repo, branch and kernel type in the `\"juniper\"` section of\nthe `meta.json`. I'd recommend running the very first build via the interface on\nthe [Binder website](https://mybinder.org), as this gives you a detailed build\nlog and feedback on whether everything worked as expected. Enter your repository\nURL, click \"launch\" and wait for it to install the dependencies and build the\nimage.\n\n![Binder](https://user-images.githubusercontent.com/13643239/39412757-a518d416-4c21-11e8-9dad-8b4cc14737bc.png)\n\n### Adding tests\n\nTo validate the code when the user hits \"Submit\", we're currently using a\nslightly hacky trick. Since the Python code is sent back to the kernel as a\nstring, we can manipulate it and add tests – for example, exercise\n`exc_01_02_01.py` will be validated using `test_01_02_01.py` (if available). The\nuser code and test are combined using a string template. At the moment, the\n`testTemplate` in the `meta.json` looks like this:\n\n```\nfrom wasabi import Printer\n__msg__ = Printer()\n__solution__ = \"\"\"${solution}\"\"\"\n${solution}\n\n${test}\ntry:\n    test()\nexcept AssertionError as e:\n    __msg__.fail(e)\n```\n\nIf present, `${solution}` will be replaced with the string value of the\nsubmitted user code. In this case, we're inserting it twice: once as a string so\nwe can check whether the submission includes something, and once as the code, so\nwe can actually run it and check the objects it creates. `${test}` is replaced\nby the contents of the test file. It's also making\n[`wasabi`](https://github.com/ines/wasabi)'s printer available as `__msg__`, so\nwe can easily print pretty messages in the tests. Finally, the `try`/`accept`\nblock checks if the test function raises an `AssertionError` and if so, displays\nthe error message. This also hides the full error traceback (which can easily\nleak the correct answers).\n\nA test file could then look like this:\n\n```python\ndef test():\n    assert \"spacy.load\" in __solution__, \"Are you calling spacy.load?\"\n    assert nlp.meta[\"lang\"] == \"en\", \"Are you loading the correct model?\"\n    assert nlp.meta[\"name\"] == \"core_web_sm\", \"Are you loading the correct model?\"\n    assert \"nlp(text)\" in __solution__, \"Are you processing the text correctly?\"\n    assert \"print(doc.text)\" in __solution__, \"Are you printing the Doc's text?\"\n\n    __msg__.good(\n        \"Well done! Now that you've practiced loading models, let's look at \"\n        \"some of their predictions.\"\n    )\n```\n\nThe string answer is available as `__solution__`, and the test also has access\nto the solution code.\n\n---\n\nFor more details on how it all works behind the scenes, see\n[the original course repo](https://github.com/ines/spacy-course).\n","funding_links":[],"categories":["CSS"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fines%2Fcourse-starter-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fines%2Fcourse-starter-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fines%2Fcourse-starter-python/lists"}