From 560913c2333ac43ff409dde092d37aeacd395028 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 1 May 2025 09:12:53 +0200 Subject: [PATCH 1/5] Update h5p.md --- book/features/h5p.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/book/features/h5p.md b/book/features/h5p.md index 3934544..776c0c9 100644 --- a/book/features/h5p.md +++ b/book/features/h5p.md @@ -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 ``` @@ -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) \ No newline at end of file +More information on H5p using the TU Delft provided hosting: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p) From d8463bf9d7d800299941263129132cf2306beb47 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 1 May 2025 07:23:50 +0000 Subject: [PATCH 2/5] Bump book/external/Sphinx-Image-Inverter from `573bb66` to `eb21e6a` Bumps [book/external/Sphinx-Image-Inverter](https://github.com/TeachBooks/Sphinx-Image-Inverter) from `573bb66` to `eb21e6a`. - [Release notes](https://github.com/TeachBooks/Sphinx-Image-Inverter/releases) - [Commits](https://github.com/TeachBooks/Sphinx-Image-Inverter/compare/573bb66332f682bdfe1d7936048780199e4a0e2d...eb21e6a80ed33f0102f9025b9ee983148370d753) --- updated-dependencies: - dependency-name: book/external/Sphinx-Image-Inverter dependency-version: eb21e6a80ed33f0102f9025b9ee983148370d753 dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- book/external/Sphinx-Image-Inverter | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter index 573bb66..eb21e6a 160000 --- a/book/external/Sphinx-Image-Inverter +++ b/book/external/Sphinx-Image-Inverter @@ -1 +1 @@ -Subproject commit 573bb66332f682bdfe1d7936048780199e4a0e2d +Subproject commit eb21e6a80ed33f0102f9025b9ee983148370d753 From 6b73abdde5ed0bf4591aff9a8b0be0445dbab7f3 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 1 May 2025 09:28:56 +0200 Subject: [PATCH 3/5] Update _config.yml --- book/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_config.yml b/book/_config.yml index 8e790c7..b54b01d 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,5 +1,5 @@ title: TeachBooks Manual -author: TeachBooks Development Team and TeachBooks users, built with TeachBooks and Jupyter Book, CC BY 4.0 +author: TeachBooks Development Team and TeachBooks users, built with TeachBooks, CC BY 4.0 execute: execute_notebooks: 'off' From 11322915b73588ad8212ab747f21233169664239 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 1 May 2025 09:31:13 +0200 Subject: [PATCH 4/5] Update intro.md --- book/intro.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/intro.md b/book/intro.md index a918590..efef43c 100644 --- a/book/intro.md +++ b/book/intro.md @@ -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 Jupyter book. 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 Jupyter book. 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. \ No newline at end of file +See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc. From 37c4c5b88a3fe587cc0a84c408c5a1db07e2f9d1 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 1 May 2025 09:34:47 +0200 Subject: [PATCH 5/5] Make distinction teachbooks and jupyter book etc more clear --- book/intro/book.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/book/intro/book.md b/book/intro/book.md index b8e7426..5d4c205 100644 --- a/book/intro/book.md +++ b/book/intro/book.md @@ -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.svg --- @@ -75,13 +75,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?