Textbook

Textbook#

We make use of an interactive online textbook to share content with students.Therefore, we make use of the TeachBooks platform, which is a spin-off of Jupyter Book.

Viewing the book#

  • Material is released to students when a commit is made to the 2025 branch at https://mude.citg.tudelft.nl/book/2025

  • Prior to sharing with students, material should be reviewed by making a commit to the 2025-draft branch. This can be viewed at https://mude.citg.tudelft.nl/book/2025-draft/.

  • All other branches are meant to be ‘in development’ and can be viewed on GitHub. Default is that the branch name is added after the root URL/repo_name. Actions page which summarizes all the branches and status: TUDelft-MUDE/book. As soon as the content is merged with the other content, these temporary branches are removed.

Editing the book#

Anyone with access can edit the book in the github repository: TUDelft-MUDE/book with the following steps:

  • Create a branch with your edits and open a draft pull request. Eventually name issues which this pull request might solve.

  • Ask for feedback from fellow content experts / TAs / content coordinator / programming coordinator.

  • As soon as it ready, mark the pull request as ready and ask the content coordinator for a merge.

  • The content coordinator will merge you pull request and delete your branch.

We identify a few user-types (taken from the TeachBooks Manual), specifically for this MUDE-book:

  • User type 1/2: review by opening an issue by clicking the lightbulb on the top-right corner of a page.

  • User type 3/4/5: edit a file on a new branch and create a merge request to 2025-draft as described above

Depending on the type of user you want to be, you need to know only a few details or a bit more. If you’re completely new, go through the general introduction to these kind of books at platforms in the ‘Your first TeachBook!’ part of the TeachBooks Manual. If you already now the basic, go through relevant pages (indicated per user type per page) in the Getting going! part of the manual.

The yearly and draft branches are protected with a ruleset. This is requiring pull requests for the with 1 approval (which hare dismissed upon new commits), requiring conversation resolution before merging, merging without rebase and blocking force pushes while allowing bypass by organization admins and the MUDE MT.

Starting in the academic year 2025-2026, we apply ‘TeachBooks versioning with academic_year.additions.errata. This is coordinated by the content coordinator.

Exercises#

For exercises in the book, we’d like to use:

FTP storage#

Images and binary or big files should be stored on our FTP-server. More information is available here. If you add an image using MyST syntax, add the FTP link like this:

```{figure} https://files.mude.citg.tudelft.nl/<filename>
---
name: figure_label
---
caption
```

If you’d like to use the download link replacer to add a button to download custom files, add those files to the FTP-server too:

```{custom_download_link} https://files.mude.citg.tudelft.nl/<path to file>
:text: "Custom text"
:replace_default: "False"
```

Are you looking for any old images that were deleted? Take a look at the repository on the tag images_archive.

Attribution#

Attribution

Written by <author(s)>

For every chapter, a note on attribution is added to make clear who are the authors. Add this note on independent pages on full-width. For chapters with multiple pages: add the note to the main page of a chapter on top in the margin. On the bottom of each of the subpages, we add the same attribution, but on the full width:

```{attributiongrey} Attribution
:class: attribution
Written by <author(s)>
```

If the page is taken from another book, add the following:

````{margin}
```{attributiongrey} Attribution
:class: attribution
Written by <author(s)>

This page reuses CC BY content from {cite:t}`<reference in book/_bibliography/references.bib>`. {fa}`quote-left`[Find out more here](external_resources)
```
````

More information about these attribution blocks can be found in the TeachBooks manual

Permissions GitHub#

Permissions are managed with GitHub teams and organization roles:

  • Teacher and TAs are added to the ‘Content writers’ team with an all-repository write role.

  • The MUDE MT team has an all-repository admin role

If you don’t have access to this repository, request for it by asking Tom (programming coordinator). If you want to start straight away, fork the book instead of creating a fork.

A bit of history#

  • 2022-23: we made one Jupyter Book for a small part of MUDE (weeks 2.7 and 2.8) used by students (everything else was on Brightspace), then a second book to archive all material (not used by students; the 2022 archive is password protected because it contains some student work).

  • 2023-24: we made our first Jupyter Book, which used (and pioneered) the draft-release workflow to release material and Sphinx Thebe interactive Python pages. Experience in MUDE inspires the creation of TeachBooks in Spring 2024.

  • 2024-25: this will be the first version of the book to be released with a CC-BY license. GitHub (TeachBooks) was used to mirror the repo and facilitate a large number of draft versions of the book that can be used for review via the github actions workflow.

  • 2025-26: all the book stuff is moved to GitHub to ease the deployment workflow (prior versions of the book used GitLab).

Preparation of 2024 Release#

Preparation of the book for release under a CC BY license took longer than expected (because Robert was in charge, of course ;)). The change requires updating the credits page, attributing each chapter/page appropriately, removing copyrighted material (e.g., images) and writing scripts to automate this process. Several things should be noted as the necessary changes are made to the book:

  1. The branch 2024 in the GitHub repository will be used to stage this work [describe/confirm tag/commit from which this branch was made this later].

  2. Tags will be used to denote the 2024 version (with a release, when ready) with TeachBooks versioning 2024.1.0 denoting the first open release under CC BY.

  3. The GitLab repository can be completely ignored, as the artifact from a tag 2024.X.X will be used for the website files.

  4. The website files for the 2024 book will be manually added to the repository github.com/tudelft-mude/2024 repository, in the book branch.

  5. There may be some commits that are already made to the 2025 and/or 2025-draft branch that should be incorporated in the 2024 version [check this later].

  6. Once the attribution and credits pages are finalized, scripts can be made to automate this process (e.g., the attribution scripts and table of contents on steroids features).

  7. This process will be repeated for the 2024 assignments

Contents