+ CO2 vs Power
+
+
+
+
+
+
+
+
+
+
+
diff --git a/book/_static/remove_author.css b/book/_static/remove_author.css
new file mode 100644
index 0000000..a99acdb
--- /dev/null
+++ b/book/_static/remove_author.css
@@ -0,0 +1,4 @@
+/* Hide the default Jupyter Book author footer */
+.component-author {
+ display: none;
+}
diff --git a/book/_toc.yml b/book/_toc.yml
index 002dfcb..6122b8d 100644
--- a/book/_toc.yml
+++ b/book/_toc.yml
@@ -12,6 +12,8 @@ parts:
chapters:
- file: installation-and-setup/user_types.md
- file: installation-and-setup/git.md
+ sections:
+ - file: installation-and-setup/tools
- file: installation-and-setup/overview.md
sections:
- file: installation-and-setup/vscode-setup.md
@@ -27,7 +29,11 @@ parts:
- file: workflows/check_changes_online.md
- file: workflows/merge_request.md
- file: installation-and-setup/collab
- - file: installation-and-setup/tools
+ - file: installation-and-setup/versioning
+ sections:
+ - file: installation-and-setup/versions_URLs
+ - file: installation-and-setup/versioning_changelog
+ - file: installation-and-setup/publisher
- file: installation-and-setup/copyright.md
sections:
- file: installation-and-setup/copyright/considerations
@@ -36,6 +42,73 @@ parts:
- caption: Features
chapters:
- file: features/overview.md
+ sections:
+ - file: features/teachbooks_intro.md
+ - file: external/deploy-book-workflow/README.md
+ - file: features/favourites.md
+ - file: external/template/README.md
+ - file: features/easy-editing.md
+ sections:
+ - file: features/write_online.md
+ - file: features/release_book_online.md
+ - file: features/draft-release
+ - file: features/pull_request_build.md
+ - file: features/local_server
+ - file: features/external_toc
+ sections:
+ - file: external/Nested-Books/README.md
+ title: (Deprecated) Share content between books using submodules
+ - file: features/update_env
+ - file: features/versioning
+ - file: features/sphinx_extensions.md
+ sections:
+ - file: external/Download-Link-Replacer/README.md
+ - file: external/Sphinx-launch-buttons/README.md
+ - file: basic-features/utterances.md
+ - file: features/h5p.md
+ sections:
+ - file: examples/h5p_examples.md
+ - file: features/plotly.ipynb
+ - file: external/Sphinx-Grasple-public/README.md
+ - file: features/HTML_javascript.md
+ sections:
+ - file: features/adding_HTML_elements.md
+ - file: features/creating_basic_HTML_elements.md
+ - file: features/live_code
+ sections:
+ - file: features/widgets.ipynb
+ - file: features/exercise_checking.ipynb
+ - file: features/jupyterquiz.ipynb
+ - file: external/sphinx-iframes/README.md
+ - external: https://github.com/TeachBooks/Sphinx-Indexed-Definitions/blob/manual/README.md
+ - file: external/Sphinx-PRIME-applets/README.md
+ - external: "https://github.com/TeachBooks/sphinx-code-examples/blob/main/MANUAL.ipynb"
+ - file: features/sphinx-proof.md
+ - external: "https://github.com/TeachBooks/Sphinx-NB-Execution-Patterns/blob/Manual/README.md"
+ - file: features/exercise.md
+ - external: https://github.com/TeachBooks/Sphinx-ref-graph/blob/manual/README.md
+ - external: https://github.com/TeachBooks/Sphinx-GitHub-Alerts/blob/main/README.md
+ - external: https://github.com/TeachBooks/Sphinx-Metadata-Figure/blob/main/MANUAL.ipynb
+ - external: https://github.com/TeachBooks/Sphinx-Gated-Directives/blob/main/MANUAL.md
+ - external: https://github.com/TeachBooks/TeachBooks-Questions/blob/main/MANUAL.md
+ - external: https://github.com/TeachBooks/TeachBooks-Fetch/blob/main/MANUAL.md
+ - file: features/visuals.md
+ sections:
+ - external: https://github.com/TeachBooks/Sphinx-Accessibility/blob/manual/README.md
+ - file: external/Sphinx-Image-Inverter/README.md
+ - file: external/JupyterBook-Patches/README.md
+ - file: external/Sphinx-TUDelft-theme/README.md
+ - file: external/teachbooks-sphinx-tippy/README.md
+ - file: features/apa
+ - file: external/Sphinx-Named-Colors/README.md
+ - external: https://github.com/TeachBooks/Sphinx-Dropdown-Toggle/blob/main/MANUAL.md
+ - external: https://github.com/TeachBooks/Sphinx-Sticky-Margin/blob/main/MANUAL.md
+ - file: features/students
+ sections:
+ - file: external/annotater/README.md
+ - file: basic-features/hypothesis.md
+ - caption: Original Jupyter Book v1 and Sphinx Features
+ chapters:
- file: basic-features/overview.md
sections:
- file: basic-features/jupyterbook.md
@@ -48,55 +121,17 @@ parts:
- file: basic-features/badges.md
- file: basic-features/banner
title: Banner or Announcement
- - file: features/easy-editing.md
- sections:
- - file: external/template/README.md
- - file: features/teachbooks
- - file: external/deploy-book-workflow/README.md
- - file: features/local_server
- - file: external/Nested-Books/README.md
- - file: features/update_env
- - file: features/sphinx_extensions.md
- sections:
- - file: external/Download-Link-Replacer/README.md
- - file: external/Sphinx-launch-buttons/README.md
- - file: basic-features/utterances.md
- - file: features/interactive_element.ipynb
- sections:
- - file: external/Sphinx-Grasple-public/README.md
- - file: features/h5p.md
- - file: features/HTML_javascript.md
- sections:
- - file: features/adding_HTML_elements.md
- - file: features/creating_basic_HTML_elements.md
- - file: features/live_code
- sections:
- - file: features/widgets.ipynb
- - file: features/exercise_checking.ipynb
- - file: features/visuals.md
- sections:
- - file: external/Sphinx-Image-Inverter/README.md
- - file: external/JupyterBook-Patches/README.md
- - file: external/Sphinx-TUDelft-theme/README.md
- - file: external/teachbooks-sphinx-tippy/README.md
- - file: features/apa
- - file: external/Sphinx-Named-Colors/README.md
- - file: features/students
- sections:
- - file: external/annotater/README.md
- - file: basic-features/hypothesis.md
-
- caption: Examples
chapters:
- file: examples/overview.md
- - file: examples/book_structure.md
- - file: examples/h5p_examples.md
- - file: examples/live_code.md
- - file: examples/example_gumbel.ipynb
- - file: examples/theory_questions.md
- - file: examples/example_quiz_interactive.ipynb
- - file: examples/coding_theory_widgets.ipynb
- - file: examples/parametric_questions.ipynb
+ sections:
+ - file: examples/book_structure.md
+ - file: examples/live_code.md
+ - file: examples/example_gumbel.ipynb
+ - file: examples/theory_questions.md
+ - file: examples/example_quiz_interactive.ipynb
+ - file: examples/coding_theory_widgets.ipynb
+ - file: examples/parametric_questions.ipynb
- caption: Editing Tools
chapters:
@@ -104,13 +139,14 @@ parts:
- file: helper_code/intro.md
sections:
- file: helper_code/converter.md
+ - file: helper_code/move_images.md
- file: external/Useful_python_code/snippit.ipynb
- file: external/Useful_python_code/extensionfildownloadreturn.ipynb
- file: external/Useful_python_code/figshrinker.ipynb
- - caption: Miscallaneous
+ - caption: Miscellaneous
chapters:
- file: references.md
- file: credits
- file: changelog
- - file: contact
\ No newline at end of file
+ - file: contact
diff --git a/book/basic-features/badges.md b/book/basic-features/badges.md
index 14fbff4..41cf07a 100644
--- a/book/basic-features/badges.md
+++ b/book/basic-features/badges.md
@@ -1,6 +1,6 @@
# Badges, Buttons & Icons
- provides a range of features which are visually appealing and functional. These elements can enhance the interactivity and visual design of your book, offering additional information or links in a compact and visually engaging way. The badges, buttons and icons are made available through Sphinx and they themselves wrote a [documentation](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html) about it.
+ provides a range of features which are visually appealing and functional. These elements can enhance the interactivity and visual design of your book, offering additional information or links in a compact and visually engaging way. The badges, buttons and icons are made available through Sphinx and they themselves wrote a [documentation](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html) about it.
(my_ref)=
## Badges
@@ -36,7 +36,7 @@ Here's an overview of all the available colours:
## Buttons
-Buttons provide a way to create clickable elements that are more attractive than links, for example, to link to key sections of your book such as downloads or external resources. Jupyter-Book supports buttons using Markdown making them highly customizable. It is possible to link to external websites as well as chapters within your book. To link to an external page, use `{button-link}`. `{button-ref}` must be used when linking to a part within your book.
+Buttons provide a way to create clickable elements that are more attractive than links, for example, to link to key sections of your book such as downloads or external resources. Jupyter-Book v1 supports buttons using Markdown making them highly customizable. It is possible to link to external websites as well as chapters within your book. To link to an external page, use `{button-link}`. `{button-ref}` must be used when linking to a part within your book.
The basic code syntax for creating a button is as follows:
@@ -49,13 +49,13 @@ The basic code syntax for creating a button is as follows:
:color: primary
```
```
-
-```{button-ref} ../features/overview.md
+[](../features/overview.md)
+```{button-ref} feature_overview
:color: secondary
```
```
- ```{button-ref} ../features/overview.md
+ ```{button-ref} feature_overview
:color: secondary
```
```
@@ -119,12 +119,12 @@ To add an icon, use the following syntax:
**1. Image Icons**
-Let's have a look at the first sentence of this chapter again: provides a range of features which are visually appealing and functional.
+Let's have a look at the first sentence of this chapter again: provides a range of features which are visually appealing and functional.
Here the Jupyter-book logo was inserted for a more professional look. It's including a link `href` and and image saved as `../images/logo-wide.svg`
```
- provides a range of features which are visually appealing and functional.
+ provides a range of features which are visually appealing and functional.
```
**2. SVG Icons**
diff --git a/book/basic-features/banner.md b/book/basic-features/banner.md
index f92f110..f61f9d1 100644
--- a/book/basic-features/banner.md
+++ b/book/basic-features/banner.md
@@ -1,6 +1,6 @@
# Banners and Announcements
-A banner can be added to the top of a Jupyter Book:
+A banner can be added to the top of a TeachBook:
```{figure} banner_mude.png
---
@@ -10,7 +10,7 @@ name: banner_mude
Example of a banner in the MUDE book.
```
-This is a commonly used feature, described in the [Jupyter Book manual here](https://jupyterbook.org/en/stable/web/announcements.html). However, note that if you are using the Sphinx-Thebe interactive Python feature, or other features that customize the top part of a Jupyter Book website (for example, the download page buttons), the banner does not always work. In this case, the banner should be specified using the `announcement` option in the `html_theme_options` setting in the `_config.yml` file:
+This is a commonly used feature, described in the [Jupyter Book v1 manual here](https://jupyterbook.org/v1/web/announcements.html). However, note that if you are using the Sphinx-Thebe interactive Python feature, or other features that customize the top part of a TeachBook (for example, the download page buttons), the banner does not always work. In this case, the banner should be specified using the `announcement` option in the `html_theme_options` setting in the `_config.yml` file:
```
sphinx:
diff --git a/book/basic-features/code.md b/book/basic-features/code.md
index 0b78694..5036154 100644
--- a/book/basic-features/code.md
+++ b/book/basic-features/code.md
@@ -2,13 +2,13 @@
There are two main ways to include code: directly within a Markdown file or within a Jupyter notebook. More methods are available, but we don't include them here. The first option is great for including simple calculations, or generating simple figures when an image file is not practical. *More will be added later.*
-Note that if you are using a `*.ipynb` file or including a code snippet in a `*.md` file, including a blank line between the text and the closing three tick marks will generate an empty code box of one line in the Jupyter Book.
+Note that if you are using a `*.ipynb` file or including a code snippet in a `*.md` file, including a blank line between the text and the closing three tick marks will generate an empty code box of one line in the TeachBook.
-When making notebooks for the Book, you might want to hide certain cells from the reader. For example, when including a simple figure generated from code or making a JupyterQuiz, we have to execute a code cell that generates the quiz. This code cell is ugly and distracting, so we do not want to render this in the final book.
+When making notebooks for the TeachBook, you might want to hide certain cells from the reader. For example, when including a simple figure generated from code or making a JupyterQuiz, we have to execute a code cell that generates the quiz. This code cell is ugly and distracting, so we do not want to render this in the final book.
-We can change how the compiler treats notebook cells by using cell tags. You can find a detailed explanation on cell tags [here](https://jupyterbook.org/en/stable/interactive/hiding.html?highlight=cell%20tag). Specifically, have a look at the sections on *hiding* cell inputs and *removing* cell inputs.
+We can change how the compiler treats notebook cells by using cell tags. You can find a detailed explanation on cell tags [here](https://jupyterbook.org/v1/interactive/hiding.html?highlight=cell%20tag). Specifically, have a look at the sections on *hiding* cell inputs and *removing* cell inputs.
-The workflow of editing cell tags depends on your editor. If you're using Jupyter Lab, you can find instructions [here](https://jupyterbook.org/en/stable/content/metadata.html#jupyter-cell-tags).
+The workflow of editing cell tags depends on your editor. If you're using Jupyter Lab, you can find instructions [here](https://jupyterbook.org/v1/content/metadata.html#jupyter-cell-tags).
For example, the following tag is used to convert the code input into either a drop-down (`hide-input`) or make it invisible (replace `hide-input` with `remove-input`). Replace `input` with `output` to do the same with the cell output:
```
diff --git a/book/basic-features/equations.md b/book/basic-features/equations.md
index 4f6d293..6223cc1 100644
--- a/book/basic-features/equations.md
+++ b/book/basic-features/equations.md
@@ -29,9 +29,11 @@ $$ F = m \cdot a = 10 \cdot 9.81 = 98 \text{N}$$
To number the equations and refer in text, you need to provide a label to the equation. Just put the label between brackets and place it after the last \$\$, like this:
- $$
- F = m \cdot a
- $$ (newtons_second_law)
+```md
+$$
+ F = m \cdot a
+$$ (newtons_second_law)
+```
Resulting in:
@@ -43,5 +45,5 @@ Equation {eq}`show_newtons_second_law` can now be referred to.
> **Note**
>
-> The Jupyter Book uses MathJax to display equations, which provides some LaTeX-like functionality, but not all! For example, the Euro symbol is missing, and packages like `siunitx` are not available (hint, use `\textrm{}` and `\textrm{}`). When something is not working, it's useful to search for MathJax-specific solutions (hint, include "mathjax" in your Google search).
+> The TeachBook uses MathJax to display equations, which provides some LaTeX-like functionality, but not all! For example, the Euro symbol is missing, and packages like `siunitx` are not available (hint, use `\textrm{}` and `\textrm{}`). When something is not working, it's useful to search for MathJax-specific solutions (hint, include "mathjax" in your Google search).
>
\ No newline at end of file
diff --git a/book/basic-features/figures.md b/book/basic-features/figures.md
index 8fcf942..3fecfae 100644
--- a/book/basic-features/figures.md
+++ b/book/basic-features/figures.md
@@ -2,29 +2,29 @@
To add a figure, just copy the figure to the correct directory. Then, in your markdown file, include the figure as follows:
-````
- ```{figure} .png/.jpg
- ---
- height/width:
- name:
- align: left / center / right
- figclass: left blank or "margin"
- ---
-
- ```
+````md
+```{figure} .png/.jpg
+---
+height/width:
+name:
+align: left / center / right
+figclass: left blank or "margin"
+---
+
+```
````
For example:
-````
- ```{figure} ../images/TUDelft_logo_rgb.png
- ---
- width: 70%
- name: demoexample1
- align: center
- ---
- example 1: width (70%) as percentage, align center
- ```
+````md
+```{figure} ../images/TUDelft_logo_rgb.png
+---
+width: 70%
+name: demoexample1
+align: center
+---
+example 1: width (70%) as percentage, align center
+```
````
provides this output, which looks nice.
@@ -39,19 +39,19 @@ example 1: width (70%) as percentage, align center
Using the name label, you can refer to the figure as done with {numref}`Figure {number} `.
-You can find more documentation on including figures [here](https://jupyterbook.org/en/stable/content/figures.html).
+You can find more documentation on including figures [here](https://jupyterbook.org/v1/content/figures.html).
There are many settings, for instance aligning right:
-````
- ```{figure} ../images/TUDelft_logo_rgb.png
- ---
- width: 50%
- name: demoexample2
- align: right
- ---
- example 2: width (50%) as percentage, align right
- ```
+````md
+```{figure} ../images/TUDelft_logo_rgb.png
+---
+width: 50%
+name: demoexample2
+align: right
+---
+example 2: width (50%) as percentage, align right
+```
````
with the result:
@@ -67,22 +67,22 @@ example 2: width (50%) as percentage, align right
Aligning right can come with the potential downside (not always wanted) that text is wrapped around the figure. To avoid this one can use `
` elements, both before and after the text (make sure to leave an empty line after the `
`!):
-````
-
- and the output
-
-
+````html
+
+and the output
+
+
- ```{figure} ../images/TUDelft_logo_rgb.png
- ---
- width: 50%
- name: demoexample3
- align: right
- ---
- example 3: width (50%) as percentage, align right with additional div style
- ```
+```{figure} ../images/TUDelft_logo_rgb.png
+---
+width: 50%
+name: demoexample3
+align: right
+---
+example 3: width (50%) as percentage, align right with additional div style
+```
-
+
````
@@ -108,16 +108,16 @@ including `figclass: margin` sets the figure to the column at the right.
-````
- ```{figure} demo97/demo97_figure1.jpg
- ---
- figclass: margin
- width: 50%
- name: demoexample2
-
- ---
- example 2:including figclass: margin
- ```
+````md
+```{figure} demo97/demo97_figure1.jpg
+---
+figclass: margin
+width: 50%
+name: demoexample2
+
+---
+example 2:including figclass: margin
+```
````
diff --git a/book/basic-features/hypothesis.md b/book/basic-features/hypothesis.md
index 0f42e79..49ebe28 100644
--- a/book/basic-features/hypothesis.md
+++ b/book/basic-features/hypothesis.md
@@ -1,11 +1,13 @@
-# Making comments on the website: Hypothesis
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for user type 1-5.
```
{bdg-warning}`Javascript overlay` {bdg-success}`Chrome Extension`
+````
+
+# Making comments on the website: Hypothesis
Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension. As this tool requires an account with a third-party, we advise to use our [local-annotator](../external/annotater/README.md) with similar capabilities but which store annotations locally. By default Hypothesis stores annotations publicly, which might confuse other students.
diff --git a/book/basic-features/jupyterbook.md b/book/basic-features/jupyterbook.md
index 6737a17..a9d7a91 100644
--- a/book/basic-features/jupyterbook.md
+++ b/book/basic-features/jupyterbook.md
@@ -1,18 +1,17 @@
-# Anatomy of a Jupyter Book
+# Anatomy of a TeachBook
-To build a Jupyter Book, you need three things:
+To build a TeachBook, you need three things:
1. A configuration file
2. A table of contents
3. Content
## The configuration file
-The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book:
+The configuration file of TeachBooks is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book:
```yaml
-title: Jupyter Book Manual
-author: Interactive Textbooks CiTG
-logo: images/TUDelft_logo_rgb.png
+title: TeachBook Manual
+author: TeachBooks development team
copyright: CC BY-NC
execute:
@@ -23,7 +22,7 @@ sphinx:
- sphinx_inline_tabs
```
-Technically speaking, a `_config.yml` file is not required to build a Jupyter Book. If you don't make one, `jupyter book` will just use all default values. However, you should make a configuration file which includes at least the following settings:
+Technically speaking, a `_config.yml` file is not required to build a TeachBook. If you don't make one, your TeachBook will just use all default values. However, you should make a configuration file which includes at least the following settings:
- `title`: the title of your book, which appears on the top-left of every page, under the logo.
- `author`: authors of the book, which appears in the bottom margin of every page.
@@ -32,7 +31,7 @@ Technically speaking, a `_config.yml` file is not required to build a Jupyter Bo
In addition, the following option can also be useful:
-- `execute_notebooks`: *turn on/off* the execution of Jupyter Notebooks during the build process. *On* by default. If you perform heavy computations in your notebook (machine learning, FEM models, et cetera), you might be better off running the notebooks on a more powerful machine as opposed to the CI/CD server. To turn it off, specify the value `'off'`. You can also exclude specific notebooks by creating exclude patterns in the filenames. For more info, see the [Jupyter Book documentation](https://jupyterbook.org/en/stable/content/execute.html#exclude-files-from-execution).
+- `execute_notebooks`: *turn on/off* the execution of Jupyter Notebooks during the build process. *On* by default. If you perform heavy computations in your notebook (machine learning, FEM models, et cetera), you might be better off running the notebooks on a more powerful machine as opposed to the CI/CD server. To turn it off, specify the value `'off'`. You can also exclude specific notebooks by creating exclude patterns in the filenames. For more info, see the [Jupyter Book v1 documentation](https://jupyterbook.org/v1/content/execute.html#exclude-files-from-execution).
```{warning}
@@ -116,6 +115,9 @@ parts:
- file: section_1_2
```
+#### Exercise
+Check out [this exercise](https://teachbooks.io/template/syntax_exercises/007.html) in the TeachBooks template to see for yourself how to structure files with titles!
+
### Including a chapter twice
In some cases you want to include the same chapter in two different places in your book (for instance parts). However, you do not want to make the same adjustments in different files, the content should only 'live' in one place. The solution is to use `include`:
diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md
index df68f69..74b4e04 100644
--- a/book/basic-features/overview.md
+++ b/book/basic-features/overview.md
@@ -1,8 +1,10 @@
-# Original Jupyter Book and Sphinx Features
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for [user type 3-5](../installation-and-setup/user_types.md).
```
+````
-These pages will provide a list of some common, basic book features which are all available in the original package. Additionally, this page includes also best-practices.
+# Overview
+
+These pages itemize some of the more common, basic book features which are all available in the original package, without requiring any additional software. They are, of course, selected with teachers and teaching applications in mind. On each page best-practices are illustrated.
diff --git a/book/basic-features/utterances.md b/book/basic-features/utterances.md
index f82a44f..cbdc82e 100644
--- a/book/basic-features/utterances.md
+++ b/book/basic-features/utterances.md
@@ -1,11 +1,13 @@
-# Discussions in your book: Utterances
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for user type 3-5.
```
{bdg-white}`GitHub app and Javascript script`
+````
+
+# Discussions in your book: Utterances
[Utterances 🔮](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab).
diff --git a/book/basic-features/videos.md b/book/basic-features/videos.md
index 3fa4506..c3b4e32 100644
--- a/book/basic-features/videos.md
+++ b/book/basic-features/videos.md
@@ -13,9 +13,9 @@ kernelspec:
# Videos
-Videos uploaded to YouTube can be embedded in the Jupyter Book. There are several ways to do so:
+Videos uploaded to YouTube can be embedded in the TeachBook. There are several ways to do so:
-**1.** To embed them in the Jupyter Book, first obtain the embedding link of the video. In order to do so, go to the *YouTube* page of the video (so not the Brightspace page), then click *share* in the description box. There should be a button *embed*, click that. Copy the HTML code that appears in the panel. Then, to embed the video, use the following
+**1.** To embed them in the TeachBook, first obtain the embedding link of the video. In order to do so, go to the *YouTube* page of the video (so not the Brightspace page), then click *share* in the description box. There should be a button *embed*, click that. Copy the HTML code that appears in the panel. Then, to embed the video, use the following
```
```
-This HTML-iframe code can be directly included in the markdown file (no need to create a code-cell).
+The src can be used in combination with [](../external/sphinx-iframes/README.md):
-Resulting in the video below:
-
-
-**2.** The above solution can be 'upgraded', setting a scaling of the video with the width of the screen and align it to the center:
+````
+```{video} https://www.youtube.com/embed/UCb-b82tzLo?
```
-
-
-
-
-
-```
-With the resulting output:
-
-
-
-
-
+````
-**3.** Another option is to use a python coding cell. As this code cell should be run when the book is made, you have to change the config file and set `execute_notebooks:` to force. This comes with the downside that it takes considerable more time to deploy the book.
+Or the HTML-iframe code can be directly included in the markdown file.
+
+Resulting in the video below:
+
+```{video} https://www.youtube.com/embed/UCb-b82tzLo?
+```
+
+**2.** Another option is to use a python coding cell. As this code cell should be run when the book is made, you have to change the config file and set `execute_notebooks:` to force. This comes with the downside that it takes considerable more time to deploy the book.
````
```{code-cell} ipython3
:tags: [remove-input]
diff --git a/book/credits.md b/book/credits.md
index 7a22754..0fe26e7 100644
--- a/book/credits.md
+++ b/book/credits.md
@@ -5,11 +5,13 @@ You can refer to this book in its entirety as:
> TeachBooks Development Team (2024), _TeachBooks Manual_. https://github.com/TeachBooks/manual. Retreived [Month, Year]. CC BY 4.0.
+This book is registered on Zenodo too: [](https://doi.org/10.5281/zenodo.15100848)
+
The introduction, structure and decisions on content is done under direction of the TeachBooks Development Team. The content is written by many contributors, of which there are many.
-We anticipate that the content of this book will change continuously. Therefore, if you'd like to refer to a specific chapter, we recommend using the source code directly with the citation that refers to the GitHub repository and lists the date and name of the file. Although content will be added over time, chapter titles and URL's in this book are expected to remain relatively static after Spring 2025. You can refer to individual chapters or pages within this book as:
+We anticipate that the content of this book will change continuously. Therefore, if you'd like to refer to a specific chapter, we recommend using the source code directly with the citation that refers to the GitHub repository and lists the date and name of the file. Although content will be added over time, chapter titles and URL's in this book are expected to remain relatively static. You can refer to individual chapters or pages within this book as:
-> `` (2024), ``. In _TeachBooks Manual_. https://github.com/TeachBooks/manual (chapter `./book/intro/`, retrieved [``]).
+> ``. In _TeachBooks Manual_. https://github.com/TeachBooks/manual (chapter `./book/intro/`, retrieved [``]).
Better yet, include a link to the specific commit! _If you know what this means, we assume you know how to do it._
@@ -54,13 +56,15 @@ The following pages are included directly from an external resource and is not e
- Page [](./external/teachbooks-sphinx-tippy/README.md). Original content licensed under MIT license.
- Page [](./external/template/README.md). Original content licensed under CC BY 4.0 license.
- Page [](./external/Sphinx-Named-Colors/README.md). Original content licensed under MIT license.
+- Page [](indexed_defintions). Original content licensed under MIT license.
+- Page [](interactive_graph_content). Original content licensed under MIT license.
- Pages [](./external/Useful_python_code/extensionfildownloadreturn.ipynb), [](./external/Useful_python_code/figshrinker.ipynb) and [](./external/Useful_python_code/snippit.ipynb). Original content licensed under BSD 3-Clause license.
The following pages contain content written by others, part of has been reused and/or modified by the TeachBooks Team:
- Pages {ref}`copyright` and {ref}`copyright_considerations` include text from {cite:t}`tud_cip_24` that is used in the copyright checklist items. Original content licensed under CC BY.
- Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified, along with paraphrased and quoted text (including hyperlinks) from {cite:t}`hall21`. Work is licensed under CC BY.
- Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified. Work is provided by Kennisland under a CC0 license. Accessed at [](https://wiki.creativecommons.org/wiki/File:CC_License_Compatibility_Chart.png) on December 17, 2024.
-
-
-
-
+- page [](./features/versioning.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0.
+- page [](./features/external_toc.md): includes text from {cite:t}`teachbooks_package` that has been modified. Original content licensed under MIT.
+- Page [](./features/exercise.md): includes text from {cite:t}`sphinx-exercise` that has been modified. Original content licensed under MIT license.
+- Page [](./features/sphinx-proof.md): includes text from {cite:t}`sphinx-proof` that has been modified. Original content licensed under MIT license.
\ No newline at end of file
diff --git a/book/examples/book_structure.md b/book/examples/book_structure.md
index db702ee..3f67fbf 100644
--- a/book/examples/book_structure.md
+++ b/book/examples/book_structure.md
@@ -1,7 +1,7 @@
# Well-Structured Book
One thing that students love is having all practical information about a course collected and updated on one page.
-No more scrolling through the introduction lecture on Brightspace while veryfing assessment methods on the online studyguide or finding out about the schedule on MyTimetable. As will be shown in the following section, a Jupyter Book can be used to clarify the logistics of a course on top of providing the course material to the students.
+No more scrolling through the introduction lecture on Brightspace while veryfing assessment methods on the online studyguide or finding out about the schedule on MyTimetable. As will be shown in the following section, a TeachBook can be used to clarify the logistics of a course on top of providing the course material to the students.
The crossover module Data Science and Artifical Intelligence for Engineers, or in short DSAIE, aims to teach powerful data science tools to 2nd master students from the Civil Engineering and Geosciences faculty. In order to do that they use a combination of practical projects and theory provided to the students through their online interactive [book](https://interactivetextbooks.citg.tudelft.nl/dsaie/intro.html).
@@ -16,7 +16,7 @@ DSAIE Overview Page
```
While the left menu shows the first two chapters in the table of contents (Home & Logistics), the right hand side menu shows the sections of the current chapter where an introduction is given on the different units of the course, the responsible lecturers as well as the schedule of lectures and practicals. Additionally, the book layout is explained to the students which can help clarify how to use the interactive sections!
-The anatomy of a jupyter book is explained more in detail on [this page](../basic-features/jupyterbook.md). In short, you can create structure in your book by having chapters and subschapters defined in the `.toc` file. In each chapter you can organize the content in sections using the `#` syntax which is visible in the menu on the right.
+The anatomy of a TeachBook is explained more in detail on [this page](../basic-features/jupyterbook.md). In short, you can create structure in your book by having chapters and subschapters defined in the `.toc` file. In each chapter you can organize the content in sections using the `#` syntax which is visible in the menu on the right.
## Tagged content
diff --git a/book/examples/example_gumbel.ipynb b/book/examples/example_gumbel.ipynb
index b366c19..6543da4 100644
--- a/book/examples/example_gumbel.ipynb
+++ b/book/examples/example_gumbel.ipynb
@@ -6,12 +6,12 @@
"tags": []
},
"source": [
- "# Programming assignment\n",
+ "# Programming assignment with checks\n",
"\n",
- "This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a Jupyter Book format with live coding. A widget has been implemented to check the answers, of which the data is included in a separate python file. The page automatically loads and a custom download page has been added\n",
+ "This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a TeachBook format with live coding. A widget has been implemented to check the answers, of which the data is included in a separate python file. The page automatically loads and a custom download page has been added\n",
"\n",
"```{Note}\n",
- "Keep in mind that Jupyter Book sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by jupyter book. In fact, in jupyter book, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.\n",
+ "Keep in mind that TeachBook sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by TeachBook. In fact, in a TeachBook, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.\n",
"```\n",
"\n",
"```{custom_download_link} ./example_gumbel_stripped.ipynb\n",
diff --git a/book/examples/h5p_examples.md b/book/examples/h5p_examples.md
index 2fb9df5..f0dafa3 100644
--- a/book/examples/h5p_examples.md
+++ b/book/examples/h5p_examples.md
@@ -1,14 +1,4 @@
-# Types of H5p Quizzes
-
-This page will show some examples of H5p quizzes built into a variety of TeachBooks to allow the students to test their understanding of the content as they read. H5p quizzes can be used to create a set of Multiple Choice, Drag and Drop, Fill in the blanks, True/False and Image choice questions so the applications are quite versitile and your imagination can be used in creating the questions.
-
-## Getting started with H5p
-
-Some best-practices on the use of H5p:
- - To startup your H5p-account, first login to H5p via Brightspace. You can follow instructions as under [https://www.tudelft.nl/teaching-support/educational-tools/h5p](https://www.tudelft.nl/teaching-support/educational-tools/h5p).
- - After that, direct login is possible via [tudelft.h5p.com](https://tudelft.h5p.com)
- - Place your H5p-elements in a shared folder in H5p.
- - Disable the display options "Toolbar Below Content" and "Display author's name to public (anonymous users) (only relevant when content's status is set to Public )" for each
+# Examples of H5p Quizzes
## Dialog cards
@@ -28,27 +18,19 @@ Problem Statement
As can be seen on the right-hand-side menu, the sub-chapter includes the problem statement, the elaboration on the model and solution method and finally an exercise for the student. The code in the page is activated by pressing the live code button which will make the code cells editable and executable. Additionally, interactive figures are included into the text with movable sliders to directly see the effect of the changes made.
-```{figure} figures/Live_code2.PNG
----
-width: 600
-align: center
----
-Interactive Graph
+```{iframe} ../_static/power.html
+:height: 580px
+:width: 100%
```
The H5p quizzes can shine in the section on questions, discussions and comments. Next to many multiple choice questions (which are discussed later) there are dialog cards which can ask more conceptual and open ended questions. Pressing on the blue button `Turn` will flip around the card and reveal the model answer. The great thing about the integration of both interactive aspects (coding and questions) helps the student to play around with the code and understand the topic from a less theoretical point-of-view.
-```{figure} figures/cards1.PNG
----
-width: 700
-align: center
----
-Dialoge Card
+```{h5p} https://tudelft.h5p.com/content/1292260184374358717/embed
```
-**Try it out!**
+```{h5p} https://tudelft.h5p.com/content/1292260188487459217/embed
+```
-
## Question Set
@@ -58,20 +40,10 @@ Question sets consist of a question and one or more possible answers to that que
The following question sets are taken from chapter 3.3. Weighted least-squares estimation of the MUDE 23/24 book. The chapter builds on the previous chapter on simple least-squares estimation and dwelves into the importance and properties of the weight matrix. The student is primarily quizzed using multiple choice questions to check their understanding. The answers can be provided in the shape of text, figures, equations, matrices and probably much more.
-```{figure} figures/Question_set_1.PNG
----
-width: 600
-align: center
----
-Text Answers
+```{h5p} https://tudelft.h5p.com/content/1292060781042105617/embed
```
-```{figure} figures/Question_set_2.PNG
----
-width: 600
-align: center
----
-Equations Answers
+```{h5p} https://tudelft.h5p.com/content/1292046737060674407/embed
```
Since these questions are meant to develop the understanding of the students, feedback is vital! Feedback can be built into the questions to explain the reasoning behind a correct answer.
@@ -96,7 +68,8 @@ Tips
Have a look at the following 7 questions.
-
+```{h5p} https://tudelft.h5p.com/content/1292062157562749767/embed
+```
## Complex fill in the blanks
@@ -106,12 +79,7 @@ The complex fill in the blanks can be used to evaluate numerical answers.
Chapter 3.7. Non-linear least-squares estimation from the MUDE 23/24 book makes use of the complex fill in the blanks quiz in order to check that the students understood the composition of the Jacobian Matrix specifically used in deriving the linearized functional model. This model is essential for accurately estimating values and assessing system behavior of complex processes that arent linear.
-```{figure} figures/blanks1.PNG
----
-width: 600
-align: center
----
-Answer Boxes
+```{h5p} https://tudelft.h5p.com/content/1292064774866067777/embed
```
As you can see, the precision of the answer sought for is specified and the figure below shows again the incorporation of feedback.
@@ -125,18 +93,24 @@ Wrong Answer + Feedback
**MUDE - Optimization**
-Since the cells can be used to evaluate numerical answers, they are an easy way to quiz the student on matrices and evaluate the result of each position indidependently. The optimization team of MUDE took this a step further and used this set-up to quiz the students on the SIMPLEX method. This method automates the solving of the augmented form of a linear programing problem with continuous variables. It makes use of tables and the manipulation of equations to find the optimal vaues. Unfortunately, with a large number of variables this tables tend to get quite big and filling in the cells becomes laborous.
+Since the cells can be used to evaluate numerical answers, they are an easy way to quiz the student on matrices and evaluate the result of each position independently. The optimization team of MUDE took this a step further and used this set-up to quiz the students on the SIMPLEX method. This method automates the solving of the augmented form of a linear programming problem with continuous variables. It makes use of tables and the manipulation of equations to find the optimal values. Unfortunately, with a large number of variables this tables tend to get quite big and filling in the cells becomes laborious.
-```{figure} figures/blanks3.PNG
----
-width: 600
-align: center
----
-SIMPLEX Method
+```{h5p} https://tudelft.h5p.com/content/1292131432784432037/embed
```
-**Try it out!**
+**Truss structure**
-
+Truss structures are modelled as rigid bars (so elements which cannot deform) connected by hinges (so elements can rotate with respect to one each other). In our model, hinges are indicate with a circle, and bars with a line. For example, the structure you've seen in the second example (with two diagonal bars removed) is modelled as follows:
+
+```{figure} ../images/Truss1.svg
+:name: truss structure
+
+Bars and hinges in truss structure
+```
+
+Now that you've been introduced to truss structures, answer the following question:
+
+```{h5p} https://tudelft.h5p.com/content/1291910926067816717/embed
+```
## True or False
@@ -154,18 +128,15 @@ align: center
Problem Statement
```
-```{figure} figures/truefalse1.PNG
----
-width: 600
-align: center
----
-True or False
+The small circles below the question indicates that there are more questions in this series which can be viewed by clicking on the blue arrow pointing towards the left or right. Open the second, fourth and fifth question:
+
+```{h5p} https://tudelft.h5p.com/content/1292120485436114287/embed
```
-The small circles below the question indicates that there are more questions in this series which can be viewed by clicking on the blue arrow pointing towards the left or right.
**Try it out!**
-
+```{h5p} https://tudelft.h5p.com/content/1292061623388939257/embed
+```
## Drag and Drop
@@ -173,16 +144,15 @@ Drag and Drop questions are useful to make the distinction between different con
**MUDE - Optimization**
-In this chapter, it was important that the students made the distinction between the terminology and mathematical meaning between different elements of the graphical solution method. A drag and drop question was used to link the term to its definition. The answer boxes can be dragged to the correct title in a playful manner.jup
+In this chapter, it was important that the students made the distinction between the terminology and mathematical meaning between different elements of the graphical solution method. A drag and drop question was used to link the term to its definition. The answer boxes can be dragged to the correct title in a playful manner.
-```{figure} figures/drag1.PNG
----
-width: 600
-align: center
----
-Drag and Drop
+The fourth question in this question set is a drag and drop question:
+
+```{h5p} https://tudelft.h5p.com/content/1292121213033110307/embed
```
+The correct answer leads to:
+
```{figure} figures/drag2.PNG
---
width: 600
diff --git a/book/examples/interactive_templates.md b/book/examples/interactive_templates.md
index 8c45e5d..65ea196 100644
--- a/book/examples/interactive_templates.md
+++ b/book/examples/interactive_templates.md
@@ -4,10 +4,10 @@ Lastly some example pages are shown which combine theory and interactive questio
1. [Programming Assignments](example_gumbel.ipynb)
- This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a Jupyter Book format with live coding.
+ This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a TeachBook format with live coding.
```{Note}
-Keep in mind that Jupyter Book sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by jupyter book. In fact, in jupyter book, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.
+Keep in mind that TeachBook sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by TeachBook. In fact, in a TeachBook, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.
```
2. [Combining theory with interactive questions and extensive coding assignments](example_quiz_interactive.ipynb)
diff --git a/book/examples/overview.md b/book/examples/overview.md
index 595f6a1..ed8fb8c 100644
--- a/book/examples/overview.md
+++ b/book/examples/overview.md
@@ -1,7 +1,3 @@
-# TeachBooks Examples
-
-This chapter will showcase some TeachBooks making great use of Jupyter Book and TeachBooks features. They can serve as an inspiring starting point for structuring your own TeachBook or just to get an idea of how other teachers and students are using it. Lastly some example pages are shown which combine theory and interactive questions and coding to different degrees.
-
-
-
+# Overview
+This chapter will showcase some TeachBooks making great use of Jupyter Book v1 and TeachBooks features. They can serve as an inspiring starting point for structuring your own TeachBook or just to get an idea of how other teachers and students are using it. Lastly some example pages are shown which combine theory and interactive questions and coding to different degrees.
diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer
index f69e970..03feccf 160000
--- a/book/external/Download-Link-Replacer
+++ b/book/external/Download-Link-Replacer
@@ -1 +1 @@
-Subproject commit f69e970a8da7d85e5473c7e5f58299a2ee3cf331
+Subproject commit 03feccf6efa55d14da78cf4259cedb8a7585ad91
diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches
index 287fb3f..99aeda4 160000
--- a/book/external/JupyterBook-Patches
+++ b/book/external/JupyterBook-Patches
@@ -1 +1 @@
-Subproject commit 287fb3f9a198848edd2063792c528c0d3d2a3a75
+Subproject commit 99aeda40ae0cfa06eb290ba5c3a6b9b81eb3992d
diff --git a/book/external/Nested-Books b/book/external/Nested-Books
index 365291d..c365e77 160000
--- a/book/external/Nested-Books
+++ b/book/external/Nested-Books
@@ -1 +1 @@
-Subproject commit 365291d0d1ba29c9d032c8ba2ec399b03e5d1176
+Subproject commit c365e770730fb5abb3426b06062e69a3a325b336
diff --git a/book/external/Sphinx-Grasple-public b/book/external/Sphinx-Grasple-public
index f4eff8d..0dc28b4 160000
--- a/book/external/Sphinx-Grasple-public
+++ b/book/external/Sphinx-Grasple-public
@@ -1 +1 @@
-Subproject commit f4eff8d1565eaf127898f2fe216cf5208684fb27
+Subproject commit 0dc28b45ef6184e67b8219bd4494c6f54ad8ccd0
diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter
index 250103c..ca1280c 160000
--- a/book/external/Sphinx-Image-Inverter
+++ b/book/external/Sphinx-Image-Inverter
@@ -1 +1 @@
-Subproject commit 250103c723aa782bcec785ae3d241cb1ffebd3d0
+Subproject commit ca1280ccadfc17f611b6f411dddb77329710dd85
diff --git a/book/external/Sphinx-Named-Colors b/book/external/Sphinx-Named-Colors
index 2ae6342..1307f44 160000
--- a/book/external/Sphinx-Named-Colors
+++ b/book/external/Sphinx-Named-Colors
@@ -1 +1 @@
-Subproject commit 2ae6342aa7d1b341d046db10de5b713cdeff4ecb
+Subproject commit 1307f44c8d64fb98ce4649f585805666e90ec3aa
diff --git a/book/external/Sphinx-PRIME-applets b/book/external/Sphinx-PRIME-applets
new file mode 160000
index 0000000..cf88491
--- /dev/null
+++ b/book/external/Sphinx-PRIME-applets
@@ -0,0 +1 @@
+Subproject commit cf8849136e1303e1a2fa2a8ed7296cde6b3b2d68
diff --git a/book/external/Sphinx-TUDelft-theme b/book/external/Sphinx-TUDelft-theme
index e4b71f8..3815645 160000
--- a/book/external/Sphinx-TUDelft-theme
+++ b/book/external/Sphinx-TUDelft-theme
@@ -1 +1 @@
-Subproject commit e4b71f810a66e302243377876f39e1dc4c4a8a6b
+Subproject commit 3815645c5cfef3ebbdc8070e649e4c7331b680e3
diff --git a/book/external/Sphinx-launch-buttons b/book/external/Sphinx-launch-buttons
index 8cfd0ba..9e70fbc 160000
--- a/book/external/Sphinx-launch-buttons
+++ b/book/external/Sphinx-launch-buttons
@@ -1 +1 @@
-Subproject commit 8cfd0ba7ae24c17e51ac0b1924473a908d4062ac
+Subproject commit 9e70fbca8fb7bacb3e6d9c58349f04d6245082dc
diff --git a/book/external/Useful_python_code b/book/external/Useful_python_code
index 7fbdbbf..c80863d 160000
--- a/book/external/Useful_python_code
+++ b/book/external/Useful_python_code
@@ -1 +1 @@
-Subproject commit 7fbdbbf720c27112fb58bcf7826225197e39357b
+Subproject commit c80863d19f7fde7a452200baa4b4fafe12debc95
diff --git a/book/external/annotater b/book/external/annotater
index 9340b4e..d1f41f9 160000
--- a/book/external/annotater
+++ b/book/external/annotater
@@ -1 +1 @@
-Subproject commit 9340b4e2856b6f2de331c31d2b74bd9dc286d276
+Subproject commit d1f41f93ffe87a305956de405dac47daaad3bc69
diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow
index 317a9cc..da54eb4 160000
--- a/book/external/deploy-book-workflow
+++ b/book/external/deploy-book-workflow
@@ -1 +1 @@
-Subproject commit 317a9cc8607f74f29957b28a86450eccba6a4e2c
+Subproject commit da54eb463cd0bac2a3e78dcce7067b2a81a8c3d1
diff --git a/book/external/sphinx-iframes b/book/external/sphinx-iframes
new file mode 160000
index 0000000..2bc21b6
--- /dev/null
+++ b/book/external/sphinx-iframes
@@ -0,0 +1 @@
+Subproject commit 2bc21b6174b8e7dbd15c862c219bd506e06f9d13
diff --git a/book/external/teachbooks-sphinx-tippy b/book/external/teachbooks-sphinx-tippy
index 338ad14..6122c67 160000
--- a/book/external/teachbooks-sphinx-tippy
+++ b/book/external/teachbooks-sphinx-tippy
@@ -1 +1 @@
-Subproject commit 338ad14d39115c620c57476931ce8fa177cf20d8
+Subproject commit 6122c67f86a7c9b95f349c80316571e277f0a66b
diff --git a/book/external/template b/book/external/template
index a8958fe..1ab90c5 160000
--- a/book/external/template
+++ b/book/external/template
@@ -1 +1 @@
-Subproject commit a8958fe48c839729226e1d1765dbf26617cf6c59
+Subproject commit 1ab90c5092b69aa8e1421e598ff43433bd97a9d8
diff --git a/book/features/HTML_javascript.md b/book/features/HTML_javascript.md
index f103638..d579423 100644
--- a/book/features/HTML_javascript.md
+++ b/book/features/HTML_javascript.md
@@ -1,4 +1,4 @@
-# Interactive HTML/JavaScript elements
+````{margin}
```{admonition} User types
:class: tip
@@ -6,15 +6,27 @@ This section is useful for user type 5.
```
{bdg-danger}`iframe`
+````
+
+# Interactive HTML/JavaScript elements
In this section, we will discuss how to [create](creating_basic_HTML_elements.md) and [embed](adding_HTML_elements.md) interactive HTML/Javascript elements created in HTML/JavaScript in a TeachBook. These HTML/Javascript element work very fluently and don't require a python kernel running in the background.
This could be for example interactive 3d figures:
-
+```{iframe} ../_static/element_render_box.html
+:width: 600px
+:height: 400px
+```
Or other interactive graphs:
-
+```{iframe} ../_static/element_pdf_and_cdf.html
+:width: 600px
+:height: 300px
+```
-
\ No newline at end of file
+```{iframe} https://openla.ewi.tudelft.nl/applet/lines_and_planes/normal_equation_plane_origin?iframe=true
+:width: 600px
+:height: 500px
+```
\ No newline at end of file
diff --git a/book/features/_ext.zip b/book/features/_ext.zip
deleted file mode 100644
index 34e2f8f..0000000
Binary files a/book/features/_ext.zip and /dev/null differ
diff --git a/book/features/adding_HTML_elements.md b/book/features/adding_HTML_elements.md
index 78a6cf0..e9cbc59 100644
--- a/book/features/adding_HTML_elements.md
+++ b/book/features/adding_HTML_elements.md
@@ -1,16 +1,30 @@
-# Adding interactive HTML/JavaScript elements
-
+````{margin}
{bdg-danger}`iframe`
+````
+
+# Adding interactive HTML/JavaScript elements
In this section, we will discuss how to embed interactive elements created in HTML/JavaScript in a TeachBook. If you are interested in learning how to create these elements yourself, we will discuss an example in the [next article](creating_basic_HTML_elements.md). As an example, let us discuss how to embed an interactive 3D model of a subsurface environment I created:
-
+```{iframe} ../_static/element_render_box.html
+:width: 600px
+:height: 400px
+```
## Storing the HTML file
TeachBooks like this one are built from a Git project, comprising of different files and folders that are assembled into a webpage. It is generally not possible to paste the code of your HTML element directly into one of the project's Markdown files. Instead, you will have to store the files separately somewhere in the folder structure, then embed them later on. For this project, the book's root folder contains a ´_static´ folder which we can use to store our HTML/JS file. Some elemenets - such as the one above - may require additional files. The HTML element above, for instance, specifies a renderer using [THREE.js](https://threejs.org/) that displays a digital model. This model is specified as an .obj file (which defines its geometry) and a .mtl file (which defines its materials - its colors, reflectivity, transparency, and so on). We can store these files in the same ´_static´ folder.
## Embedding HTML files via iframes
-If we want to embed our HTML/JS element in a Markdown page, we must use an inline frame, also known as an iframe. In code, an iframe looks like this:
+If we want to embed our HTML/JS element in a Markdown page, we must use an inline frame, also known as an iframe. In a book, an iframe can be added using [](../external/sphinx-iframes/README.md):
+
+````
+```{iframe} ../_static/element_render_box.html
+:width: 600px
+:height: 300px
+```
+````
+
+or alternatively using raw HTML:
```html
diff --git a/book/features/apa.md b/book/features/apa.md
index a3b5d03..910c788 100644
--- a/book/features/apa.md
+++ b/book/features/apa.md
@@ -1,100 +1,133 @@
-(apa)=
-# APA References
-
+````{margin}
```{admonition} User types
:class: tip
This page is useful for user type 4 and 5.
```
-{bdg-primary}`(To be converted into) Sphinx Extension`
+{bdg-primary}`Sphinx Extension`
-```{note}
-This feature is stable but because it relies on a local extension that is part of your book files and _not_ managed as part of a computing environment (e.g., `pip` or `conda`), unknown issues may arise. We would like to convert this feature into an independent Sphinx extension and/or Pybtext plugin. Visit the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17) to learn more.
+````
-The instructions provided here will work under conventional usage with Jupyter Book (e.g., `jupyter book build book`).
-
-A temporary fix has also been implemented in the TeachBooks package for use with the Deploy Book Workflow (release mode) (see [release notes from v0.1.0](https://github.com/TeachBooks/TeachBooks/releases/tag/v0.1.0)).
-```
+(apa)=
+# APA References
## Introduction
-Do you include references in your book, but you're tired of the default options available in Jupyter Book? For example, the square-bracket style of citation and reference, where the first three letters of the name year are combined in a way that seems designed to minimize transparency?
+Do you include references in your book, but you're tired of the default options available in a TeachBook / Jupyter Book v1? For example, the square-bracket style of citation and reference, where the first three letters of the name year are combined in a way that seems designed to minimize transparency?
There is a solution! This extension allows you to have APA formatting in your book.
## Installation
-To use APA-references, a set of Python files need to be manually loaded into your book
-**Step 1: files to root directory of your book**
+To use APA-references, install the [Sphinx-APA-References extension](https://github.com/TeachBooks/Sphinx-APA-References) by following these two steps:
-Download this zip-file [`_ext.zip`](_ext.zip), which contains the necessary files, unzip it and place the contents in the root of your book directory so that it looks like the schematic here:
+**Step 1: Install the Package**
+Install the module `sphinx-apa-references` package using `pip`:
```
-book
-├── _ext/
-│ ├── pybtexapastyle/
-│ ├── apastyle.py
-│ ├── bracket_citation_style.py
-├── _config.yml
-├── _toc.yml
-├── requirements.txt
-├──
+pip install sphinx-apa-references
```
-
+
**Step 2: Add to `requirements.txt`**
-Add a specific version of `docutils` to your requirements file:
+Make sure that the package is included in your project's `requirements.txt` to track the dependency:
```
-docutils==0.17.1
+sphinx-apa-references
```
**Step 3: Enable in `_config.yml`**
-In your `_config.yml` file, add a `bibtex_default_style`, `bybtex_reference_style` and the local extensions `apastyle` and `bracket_citation_style.py`
+In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time) and specify the location of your bib file (note indentation of the bibtex file path specification; any number of bib files are allowed):
```
-sphinx:
- config:
- ...
- bibtex_default_style: myapastyle
- bibtex_reference_style: author_year_round
- local_extensions:
- apastyle: _ext/
- bracket_citation_style: _ext/
- ...
+sphinx:
+ extra_extensions:
+ .
+ .
+ .
+ - sphinx_apa_references
+ .
+ .
+ .
+bibtex_bibfiles: "/references.bib"
```
## Usage
-All references are now made in APA-style. See for example this reference: {cite:t}`jason_moore` which shows up on the [references page](../references.md) too. The form of the citation looks like this:
+All references are now made in APA-style. Here are five examples how to create a citation in APA style:
+
+| Syntax | Result with 1 author | Result with many authors | Explanation |
+| :---: | :---: | :---: | :---: |
+|`{cite:t}` | {cite:t}`jason_moore` | {cite:t}`dummyreference` | Textual citation |
+|`{cite:p}`| {cite:p}`jason_moore` | {cite:p}`dummyreference` | Parenthetical citation |
+|`{cite}`| {cite}`jason_moore` | {cite}`dummyreference` | Same as `{cite:p}` |
+|`{cite:ts}` | {cite:ts}`jason_moore` | {cite:ts}`dummyreference` | Same as `{cite:t}`, but without abbreviation of authors |
+|`{cite:ps}`| {cite:ps}`jason_moore` | {cite:ps}`dummyreference` |Same as `{cite:p}`, but without abbreviation of authors |
+
+For more options on the in-line citation style, see https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style.
+
+The references section at the end of your book will also be formatted in APA style:
+
+::::{admonition} Example of APA References
+:class: example
+
+```{iframe} ../references.html
+:class: no-blend
+```
+::::
+
+## Duplicate label warning
+
+You might encounter a warning during the build process that has this structure:
```
-{cite:t}`jason_moore`
+:: WARNING: duplicate label ", " for keys "" and ""
```
-Here are three examples for making citations:
+This is might have different cause, but often it is because two different references have the same author(s) and the same year. A common solution is to add letters to the year in the `.bib` file, like this:
-| Syntax | Result |
-| :---: | :---: |
-|`{cite:t}` | {cite:t}`jason_moore` |
-|`{cite:p}`| {cite:p}`jason_moore` |
-|`{cite}`| {cite}`jason_moore` |
+```bibtex
+@misc{launch_buttons,
+ author = {{TeachBooks}},
+ title = {Custom launch buttons},
+ url = {https://github.com/TeachBooks/Sphinx-launch-buttons},
+ year = {2024a},
+ note = {Retrieved December, 2024. BSD-3-Clause.},
+}
-For more options on the in-line citation style, see https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style.
+@misc{nested,
+ author = {{TeachBooks}},
+ title = {Git workflow: Share content between book},
+ url = {https://github.com/TeachBooks/Nested-Books},
+ year = {2024b},
+ note = {Retrieved December, 2024. CC BY 4.0.},
+}
-### Known Issues
+```
-Two issues are known:
-- During the build, warning will be raised with `... WARNING: duplicate label for keys ...`. In most cases, these warnings can be ignored. As noted above, the book will not build references properly
-- In case you have both an `.ipynb` and `.md` version of a file, the `.md` version will always be used whenever this extension is used. This reomved the possibility to show code outputs.
+This does negate the automatic ordering of references by the order `authors > year > title`, so our advice is to only use this solution when the bibliography contains duplicate author-year combinations ánd the bibliography is final. That way the you can use the sorted order with warnings to determine the correct letters to add to the years.
## Implementation
The extension is based on [`pybtex`](https://pybtex.org/), which is a BibTeX-compatible bibliography processor in Python that is extendible with plugins.
-Although some customization is possible with the standard Jupyter Book features, [as described here](https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style), this extension implements the complete APA style, as well as enforcing round brackets (like this).
+Although some customization is possible with the standard Jupyter Book v1 features, [as described here](https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style), this extension implements a complete APA style, as well as enforcing round brackets (like this).
-The need to enforce `docutils==0.17.1` version is the only known solution to the issue where empty brackets `[]` are left on the references page.
+### Previous implementation
-## Contribute
+APA referencing was previously implemented by including a local extension in a book subdirectory `_ext` (described [here](https://github.com/jupyter-book/jupyter-book/issues/1090)). To upgrade, once this Sphinx extension is implemented in your book, the local extension files in `_ext` can be deleted and the four lines indicated below removed from your `_config.yml` file:
-This tool needs to be developed further to make it into a proper sphinx-extension (and/or an independent `pybtext` plugin). The process is described in this [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17). If you've ideas or questions, please reach out to us at info@teachbooks.io!
+```yaml
+sphinx:
+ config:
+ .
+ .
+ .
+ bibtex_reference_style: author_year_round # remove
+ bibtex_default_style: myapastyle # remove
+ .
+ .
+ .
+ local_extensions:
+ apastyle: _ext/ # remove
+ bracket_citation_style: _ext/ # remove
+```
\ No newline at end of file
diff --git a/book/features/buildbook.md b/book/features/buildbook.md
index c9acb3e..3d9a957 100644
--- a/book/features/buildbook.md
+++ b/book/features/buildbook.md
@@ -8,7 +8,7 @@ Now that we have talked about how you can collaborate using git, it's time to ex
## Pipeline
-Both GitLab and GitHub make use of CI/CD to publish the jupyter books. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of jupyter books focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available.
+Both GitLab and GitHub make use of CI/CD to publish the TeachBooks. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of TeachBooks, it focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available.
Concretely, Continuous Integration means that whenever changes are pushed to the repository (where does the publish branch come in?) the pipeline is triggered. Moreover, the pipeline also builds the book which is composed out of multiple .md or .ipynb files and converts those files into HTML.
diff --git a/book/features/creating_basic_HTML_elements.md b/book/features/creating_basic_HTML_elements.md
index 806395d..88346f9 100644
--- a/book/features/creating_basic_HTML_elements.md
+++ b/book/features/creating_basic_HTML_elements.md
@@ -1,6 +1,9 @@
# Creating basic interactive HTML/JavaScript elements
-
+```{iframe} ../_static/element_pdf_and_cdf.html
+:width: 600px
+:height: 300px
+```
At the bottom of this page, I will provide the full code for the interactive element above. In this section, let us go through the code one piece at a time. Let us begin from the top.
@@ -50,7 +53,7 @@ The first few lines of our JavaScript code are simple. To scale our element with
var width = vw;
// Create the canvas. We will use only part of it for the main plot
- var svg = d3.select("#click") // This selects the div
+ var svg = d3.select("#click") // This selects the svg using its id
.attr("width", width) // This defines the canvas' width
.attr("height", height) // This defines the canvas' height
```
@@ -850,4 +853,4 @@ Here is the code for the element above in full: