mirror of
https://github.com/google/comprehensive-rust.git
synced 2024-12-16 06:39:46 +02:00
6d19292f16
I've taken some work by @fw-immunant and others on the new organization of the course and condensed it into a form amenable to a text editor and some computational analysis. You can see the inputs in `course.py` but the interesting bits are the output: `outline.md` and `slides.md`. The idea is to break the course into more, smaller segments with exercises at the ends and breaks in between. So `outline.md` lists the segments, their duration, and sums those durations up per-day. It shows we're about an hour too long right now! There are more details of the segments in `slides.md`, or you can see mostly the same stuff in `course.py`. This now contains all of the content from the v1 course, ensuring both that we've covered everything and that we'll have somewhere to redirect every page. Fixes #1082. Fixes #1465. --------- Co-authored-by: Nicole LeGare <dlegare.1001@gmail.com> Co-authored-by: Martin Geisler <mgeisler@google.com>
76 lines
2.4 KiB
Markdown
76 lines
2.4 KiB
Markdown
# mdbook-course
|
|
|
|
This is an mdBook preprocessor to handle some specific details of Comprehensive
|
|
Rust.
|
|
|
|
## Frontmatter
|
|
|
|
The preprocessor parses "frontmatter" -- YAML between `---` at the beginning of
|
|
a Markdown file -- and removes it from the rendered result.
|
|
|
|
Frontmatter is optional, and can contain any of the following fields, defined
|
|
below:
|
|
|
|
```yaml
|
|
minutes: NNN
|
|
course: COURSE NAME
|
|
session: SESSION NAME
|
|
```
|
|
|
|
## Course Structure
|
|
|
|
A book can contain multiple _courses_. Each course is made up of _sessions_,
|
|
which are blocks of instructional time (and include breaks). Typically two
|
|
sessions are taught per day, morning and afternoon.
|
|
|
|
Each session is comprised of _segments_, which are slides on a related theme.
|
|
Breaks are scheduled between segments.
|
|
|
|
Each segment is comprised of _slides_. A slide can be made up of one or more
|
|
mdBook chapters.
|
|
|
|
The course structure is derived from the mdBook structure. Each top-level mdBook
|
|
"section" is treated as a segment, and may optionally begin a new session or
|
|
course. Within each section, the first chapter and subsequent second-level
|
|
chapters are each treated as a slide. Any further-nested chapters are treated as
|
|
parts of the parent slide. For example:
|
|
|
|
```ignore
|
|
- [Frobnication](frobnication.md)
|
|
- [Integer Frobnication](frobnication/integers.md)
|
|
- [Frob Expansion](frobnication/expansion.md)
|
|
- [Structs](frobnication/expansion-structs.md)
|
|
- [Enums](frobnication/expansion-structs.md)
|
|
- [Exercise](frobnication/exercise.md)
|
|
- [Solution](frobnication/Solution.md)
|
|
```
|
|
|
|
In this segment, there are four slides: "Frobnication", "Integer Frobnication",
|
|
"Frob Expansion", and "Exercise". The last two slides are made up of multiple
|
|
chapters.
|
|
|
|
The first chapter of a segment can use the `course` and `session` fields in its
|
|
frontmatter to indicate that it is the first segment in a session or course.
|
|
|
|
## Timing
|
|
|
|
Each chapter should specify an estimate of the instructional time it will
|
|
require in the `minutes` field. This information is summed, with breaks
|
|
automatically added between segments, to give time estimates for segments,
|
|
sessions, and courses.
|
|
|
|
## Directives
|
|
|
|
Within the course material, the following directives can be used:
|
|
|
|
```
|
|
{{%segment outline}}
|
|
{{%session outline}}
|
|
{{%course outline}}
|
|
{{%course outline COURSENAME}}
|
|
```
|
|
|
|
These will be replaced with a markdown outline of the current segment, session,
|
|
or course. The last directive can refer to another course by name and is used in
|
|
the "Running the Course" section.
|