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

book/_config.yml

@@ -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'

book/external/Sphinx-Image-Inverter

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

book/external/deploy-book-workflow

@@ -1 +1 @@
-Subproject commit 427215f1ccc048847abd8cd86a1ba2e85c2dd549
+Subproject commit d90524baa6d989dc2f49ee3d5d2ae1885fe679a9

book/external/template

@@ -1 +1 @@
-Subproject commit 352ce2076e32e852f0d718f8f4ed414898821365
+Subproject commit 8424c5e1fb5631474250859482b92fc1761c502f

book/features/draft-release.md

@@ -29,7 +29,7 @@ The workflow is enabled by a `teachbooks` CLI feature that identifies and remove
 
 For example, pages in a developed book (e.g., `draft` branch) can be manually stripped out of the table of contents when a merge request from `draft` to `release` is made. This prevents the page being included in the released book. Pages marked with this feature are still visible in the `draft` book. Lines tagged in the configuration file `_config.yml` can be used in exactly the same manner. The tag is applied as follows:
 
-```
+```yaml
 format: jb-book
 root: intro
 
@@ -38,9 +38,9 @@ parts:
     chapters: 
     - file: ...
       ...
-# START REMOVE-FROM-PUBLISH
+# START REMOVE-FROM-RELEASE
     - file: files_to_remove
-# END REMOVE-FROM-PUBLISH
+# END REMOVE-FROM-RELEASE
 ```
 
 There is no limit to the number of stripped sections, they can be sequential and indentation does not matter.
@@ -48,9 +48,11 @@ There is no limit to the number of stripped sections, they can be sequential and
 To invoke the tag and remove content during the book build process, use the following optional argument when building the book with the `teachbooks` package:
 
 ```
-teachbooks build --publish book
+teachbooks build --release book
 ```
 
+This is done in the [deploy-book-workflow](deploy-book-workflow) by including the branches for which preprocessing needs to be done the repository variable `BRANCHES_TO_PREPROCESS` which is by default set to ` ` (just a space = no branch). It should be a space-separated list of branch names, e.g. 'main second third'.
+
 Note that `teachbooks build book` would build a book without stripping the tagged lines, just as `jupyter-book build book` would. This is called "draft mode" and is the default behavior. You can recognize it in the stdout after running the `build` command:
 
 ```bash

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
 <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)

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 <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.

book/intro/book.md

@@ -1,15 +1,16 @@
 # 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
+:class: blend
 ```
 
-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 +38,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,25 +64,23 @@ 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
 
-```{figure} figures/intro-book.svg
----
-width: 700px
----
 The process of building a book with TeachBooks. When just getting started, TeachBooks tools enables you to focus on what matters most: learning to write content for your book!
 ```
 
 ```{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?