Environments¶
General¶
Keywords can be entered at the start of any markdown cell in a notebook to indicate that it requires additional markup. We call these specailly marked up cells environments. The general syntax is ## Keyword: Optional title, where:
- There can be any number of hashes at the start
- The keyword that defines the environment
- A colon is required, even if no optional title is provided
- An optional title can be given, which will appear in the cell
This structure for the keywords was chosen so that it still displays well in an unrendered notebook, ie: when you are creating the material. The specific format has been chosen for ease of use and to mitigate against accidental decoration.
All headings get normalised to ## regardless of how many hashes are used
The keywords available by default, in the order they will normally be encountered, are
PrerequisitesScheduleSetupThese are ususally reserved for the00_schedule.ipynbpage, but can be used elsewhere if required andOverviewInformationExerciseSolutionKey PointsThese are normally found in eachXX_episode.ipynbpage.
Below we outline how each environment works. In the sections on keywords and template, we outline how we can change some of the default behaviour.
Format¶
We give a description of each environment.
This will be followed by three 'cells':
- The first uses
%%markdownmagic to show what the plain text you enter looks like. - The output of this cell, the second 'cell' is how the environment will render in the plain notebook
- The third cell is what the cell will look like once
nbfancy renderhas been used.
You should just enter the plain text after %%markdown into a markdown cell in a notebook and once rendered it will appear as the third example.
Prerequisites¶
By default the prerequisites environment is coloured green, is higlighted with a star symbol and the keyword is kept in the title.
%%markdown
## Prerequisites:
* Bulleted
* List
* of
* items
Schedule¶
The schedule environment is white as most of the body will usually be filled with a table of links to the various parts of the lesson. It uses the clock symbol and by default the keyword is kept.
%%markdown
## Schedule:
| Time | Episode | Description |
|---|---|---|
| 0:00 | [Introdction](01_intro.ipynb) | A good start |
| 0:10 | [Part One](02_part_one.ipynb) | The first part |
| 0:20 | [Part Two](03_part_two.ipynb) | The next part |
Setup¶
The setup environment is also green, in general the first and last environment you see on each page will be green, but none on the intermediate environments will be. The symbol is gears and the keyword is retained.
When the setup is lengthy we have alternatively included a specific notebook 00_setup.ipynb and an additional link in the schedule.
%%markdown
## Setup:
Install NBfancy by executing `pip install nbfancy`
Overview¶
The overview environment appears at the start of each section or episode and hence is coloured green. It has uses the page icon and retains the keyword. The overview environment is useful for outlining the timings for a section, the key questions that will be answered and the learning objectives. We suggest the following layout:
%%markdown
## Overview:
- **Teaching:** 10 min
- **Exercises:** 10 min
**Questions**
- Is this a list of questions?
**Objectives**
- This is a list of outcomes
Information¶
The information environment is coloured blue and can be used anywhere in the body of a lesson where special attention is required or additional information is available. It uses the information circle symbol and the keyword is removed on use. This means that the optional title will be used as the title, and if no optional title is provided, only the symbol will appear.
%%markdown
## Information: A useful tip
Here is some additional information about that thing we just did
Exercise and Solution environments¶
The exercise environment is yellow and has a pencil and pad as a symbol. The keyword is removed on use, but you can use the optional title to give exercises titles with a number at the start if desired. There are number of ways of using the exercise environment and its optional partner, solution.
The solution environment is blue and uses the eye symbol. As with the exercise environment the keyword is removed, and a number can be used at the start. You won't see any solution environments on this page! So as not to give the answers immediately after the exercise the solutions are placed in a seperate notebook. This allows you to create an exercise and solution together, but these get seperated by the NBfancy tool. The solution link defined in the exercise will point to the solutions page and even scroll the page to the relevant solution, if it were to appear off screen.
We will demonstrate four different ways of using the exercise/solution environments.
Exercise only¶
First an exercise with no solution, for when no solutions is provided/required.
%%markdown
## Exercise: 1
Do the first task
Exercise and separate solution¶
Second an exercise with no inline solution, but which creates a link to a solution notebook. This is useful if you have already defined solutions in a separate notebook. Currently, the notebooks must have the same root name but with the solution ending with -soln. That is if your notebook is called 01_lesson.ipynb then the link will point to 01_lesson-soln.ipynb.
If the exercise environment ends with an empty markdown link: [Solution]() then a link will be created to the solution automatically, if it has the same title.
%%markdown
## Exercise: 2
Do the second task
[Solution]()
Exercise and solution, missing link¶
Third an exercise with a solution defined after it, but no link included in the exercise. This is usually an error, but included to demonstrate that the solution is not lost, just difficult to get to!
%%markdown
## Exercise: 3
Do the third task
%%markdown
## Solution: 3
Everyone gets stuck on number 3
BIG BLANK SPACE REQUIRED
Exercise and Solution¶
Fourth and finally an exercise with a solution defined after it, with an empty link included in the exercise. This is the intended typical use of the exercise and solution pair.
%%markdown
## Exercise: 4
Do the fourth task
[Solution]()
%%markdown
## Solution: 4
The fourth task was trivial
BIG BLANK LESS NECESSARY
Key Points¶
The key points environment is typically used to close an episode and is coloured green. It uses the key as a symbol and the keyword is kept. By way of example, we will summarise the key points of this section here.
%%markdown
## Key Points:
- The general keyword syntax is `## Keyword: Optional title`
- `Prerequisites`, `Schedule` and `Setup` are generally used on the first page
- Sections start with an `Overview` and finish with `Key Points`
- `Information` highlights additional information in the lesson
- `Exercise` and `Solution` can be used as a pair to set exercises