admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'release' of https://github.com/TeachBooks/manual into release

Browse source
This commit is contained in:
Tom van Woudenberg 2025-05-01 09:58:09 +02:00
commit 9e00076255
5 changed files with 18 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

2
book/_config.yml
View file

@ -1,5 +1,5 @@
title: TeachBooks Manual
author: TeachBooks Development Team and TeachBooks users, built with <a href="https://teachbooks.io/">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a>
author: TeachBooks Development Team and TeachBooks users, built with <a href="https://teachbooks.io/">TeachBooks</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a>
execute:
execute_notebooks: 'off'

2
book/external/Sphinx-Image-Inverter vendored

@ -1 +1 @@
Subproject commit 573bb66332f682bdfe1d7936048780199e4a0e2d
Subproject commit eb21e6a80ed33f0102f9025b9ee983148370d753

8
book/features/h5p.md
View file

@ -10,14 +10,16 @@ This section is useful for user type 3-5.
# H5p interactive elements
## Instruction
H5p elements are interactive HTML-blocks which can be embedded in a Jupyter Book using an iframe. An H5p element can be created in the [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first). The iframe code can be copied at Edit - Publish - Public - Embed code. This html code can be directly added to your markdown file using [](../external/sphinx-iframes/README.md):
H5p elements are interactive HTML-blocks which can be embedded in a Jupyter Book using an iframe. H5p requires a server to host those elements. For TU Delft employees, this is arranged for on a [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first as described [here](https://www.tudelft.nl/teaching-support/educational-tools/h5p)).
After creating an H5p element, the iframe code can be copied at Edit - Publish - Public - Embed code. This html link of that embed can be directly added to your markdown file using [](../external/sphinx-iframes/README.md):
````
```{h5p} https://....h5p.com/content/.../embed
```
````
Alternative, you can use raw html:
Alternative, you can use raw html (lacking proper dark mode conversion):
```html
<iframe src="https://....h5p.com/content/.../embed" aria-label="..." width="1088" height="200" frameborder="0" allowfullscreen="allowfullscreen" allow="autoplay *; geolocation *; microphone *; camera *; midi *; encrypted-media *"></iframe><script src="https://tudelft.h5p.com/js/h5p-resizer.js" charset="UTF-8"></script>
```
@ -39,4 +41,4 @@ Some best-practices on the use of H5p:
In the next subpage, these exampled are shown.
More information on H5p using the TU Delft provided hosting: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p)
More information on H5p using the TU Delft provided hosting: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p)

6
book/intro.md
View file

@ -1,8 +1,8 @@
# TeachBooks Manual
This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="images/logo-wide.svg" alt="Jupyter book"></a>. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users. We hope you find this resource useful and refer back to it often.
This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="images/logo-wide.svg" alt="Jupyter book"></a>. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users with many additional features developed for education-purposes. We hope you find this resource useful and refer back to it often.
TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our community beyond Delft and welcome contributions from all users.
TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our open source community beyond Delft and welcome contributions from all users.
For more information about TeachBooks, visit [https://teachbooks.io/](https://teachbooks.io/). Do not hesitate to reach out via email at [info@teachbooks.io](mailto:info@teachbooks.io) or contribute on GitHub via discussions, issues or pull requests.
@ -16,4 +16,4 @@ There are several "parts" to the manual:
- The **Features** part describes a suite of tools that are useful for teachers, many of which are developed by TeachBooks contributors specifically for use in education. Many of these tools are illustrated in the **Examples**.
- A few special tools are included in the **Editing Tools** that are useful when writing content.
See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc.
See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc.

16
book/intro/book.md
View file

@ -1,15 +1,15 @@
# What is a TeachBook?
Never seen a TeachBook before? Here's a small demo of our MUDE-book!
Never seen a TeachBook before? Here's a small demo of the MUDE-book!
```{video} https://www.youtube.com/embed/gbBsWo6em4c?si=ayKhISsx06LmGbDD
```
So what are you looking at? It's a website generated with the [Jupyter Book package](https://jupyterbook.org/). Various extensions have been added to improve the student-experience, especially for technical topics! The actual website you're looking at now is a Jupyter Book. With TeachBooks we aim to make it easy to collaboratively use it, even if you've little experience with the software package which is part of it.
So what are you looking at? It's a website generated with the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) which in turn makes use of many other tools, of which [Jupyter Book package](https://jupyterbook.org/) and [Sphinx](https://www.sphinx-doc.org/) are the most prominent. Various extensions have been added to improve the student-experience, especially for technical topics! With TeachBooks we aim to make it easy to collaboratively use it, even if you've little experience with the software package which is part of it.
## Three Key Ingredients
To create a Jupyter Book, three key ingredients are needed:
To create a TeachBook, three key ingredients are needed:
1. A **configuration file** to define functionalities, `_config.yml`
2. A **table of contents** file to list which files should end up in the book, `_toc.yml`, as well as define its structure
@ -37,7 +37,7 @@ Note the arrangement of the 3 key book ingredients in a subdirectory called `boo
`````{admonition} Text-based files? yml? What is that?!
:class: tip, dropdown
Text-based files are digital files on your computer that you can open in a text editor and read directly. There are many file extensions used for text-based files, a few common ones related to Jupyter Book are: Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), and YAML (`*.yml`).
Text-based files are digital files on your computer that you can open in a text editor and read directly. There are many file extensions used for text-based files, a few common ones related to TeachBooks are: Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), and YAML (`*.yml`).
YAML (or YML) is a text-based file format that is primarily used to store data. It is useful because it is easy for humans to read and write, and easy for machines to _parse_ and generate., which is why YAML is often used for configuration files. Here is an example of a YAML file...can you tell what information is being stored?
@ -63,7 +63,7 @@ You can see quite clearly that a number of files are listed, and that they are o
## How is a book made?
A book is made by by writing content in text-based files such as Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), etc. After that, software is used to "parse" these files and create the final book (e.g., Jupyter Book). Fortunately when getting started you don't need to worry about the software because TeachBooks has set up GitHub tools for you that take care of this process automatically! The process is illustrated in the diagram below.
A book is made by by writing content in text-based files such as Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), etc. After that, software is used to "parse" these files and create the final book (e.g., website). Fortunately when getting started you don't need to worry about the software because TeachBooks has set up GitHub tools for you that take care of this process automatically! The process is illustrated in the diagram below.
```{figure} figures/intro-book-2.svg
@ -73,13 +73,13 @@ The process of building a book with TeachBooks. When just getting started, Teach
```{admonition} Familiar with LaTeX? There are similarities!
:class: dropdown
Have you ever used LaTeX? It turns out there are a lot of similarities with Jupyter Book. Here is a quick list:
Have you ever used LaTeX? It turns out there are a lot of similarities with TeachBooks. Here is a quick list:
1. Writing "source code" in text-based files (i.e., `*.tex` versus `*.md`, `*.ipynb`, etc) that is generally easy to read without the markup and uses special functions to format rich document objects (e.g., tables, figures, etc).
2. The "book" is created by using a piece of software that parses the source code and creates the final document (a `*.pdf` versus a `*.html` for Jupyter Book).
2. The "book" is created by using a piece of software that parses the source code and creates the final document (a `*.pdf` versus a `*.html` for TeachBooks).
3. Creating the document structure using a list of files that contain source code that automatically generates the Table of Contents and Index..
4. Sometimes you can spend more time than you like troubleshooting "bugs" that turn out to be simple syntax errors.
If you've used LaTeX before, it will be relatively easy to learn to use a Jupyter Book.
If you've used LaTeX before, it will be relatively easy to learn to use a TeachBook.
```
## Why are Git and GitHub Important?