From fdf2d7c5ef45e501d6234063ce3e15e04742d03e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 3 Nov 2025 17:48:38 +0100 Subject: [PATCH] Jupyterbook v1 and teachbooks --- .github/workflows/call-deploy-book.yml | 2 +- CITATION.cff | 2 +- README.md | 4 ++-- book/_toc.yml | 2 +- book/basic-features/badges.md | 8 ++++---- book/basic-features/banner.md | 4 ++-- book/basic-features/code.md | 4 ++-- book/basic-features/equations.md | 2 +- book/basic-features/jupyterbook.md | 15 +++++++-------- book/basic-features/overview.md | 2 +- book/basic-features/videos.md | 4 ++-- book/examples/book_structure.md | 4 ++-- book/examples/example_gumbel.ipynb | 4 ++-- book/examples/interactive_templates.md | 4 ++-- book/examples/overview.md | 2 +- book/external/Download-Link-Replacer | 2 +- book/external/JupyterBook-Patches | 2 +- book/external/Nested-Books | 2 +- book/external/Sphinx-Grasple-public | 2 +- book/external/Sphinx-Image-Inverter | 2 +- book/external/Sphinx-TUDelft-theme | 2 +- book/external/Sphinx-launch-buttons | 2 +- book/external/deploy-book-workflow | 2 +- book/external/template | 2 +- book/features/apa.md | 6 +++--- book/features/buildbook.md | 2 +- book/features/custom-launch-button.md | 2 +- book/features/draft-release.md | 2 +- book/features/h5p.md | 2 +- book/features/jupyterlite/configuration.md | 6 +++--- book/features/jupyterlite/jupyterlite.md | 2 +- book/features/live_code.ipynb | 6 +++--- book/features/local_server.md | 2 +- book/features/overview.md | 2 +- book/features/pull_request_build.md | 2 +- book/features/release_book_online.md | 2 +- book/features/sphinx_extensions.md | 2 +- book/features/teachbooks_intro.md | 4 ++-- book/features/update_env.md | 2 +- book/features/widgets.ipynb | 6 +++--- book/helper_code/converter.md | 2 +- book/helper_code/intro.md | 2 +- book/installation-and-setup/anaconda.md | 4 ++-- book/installation-and-setup/copyright/licenses.md | 2 +- .../copyright/recommendations.md | 2 +- book/installation-and-setup/git-setup_local.md | 2 +- .../git_bash_conda_vs-code.md | 2 +- book/installation-and-setup/jupyter-book-setup.md | 6 +++--- book/installation-and-setup/overview.md | 2 +- book/installation-and-setup/user_types.md | 4 ++-- book/installation-and-setup/vscode-setup.md | 2 +- book/intro.md | 4 ++-- book/intro/next.md | 2 +- book/intro/template.md | 4 ++-- book/workflows/collaboration.md | 2 +- book/workflows/edit_book.md | 2 +- book/workflows/user45_check_changes.md | 2 +- 57 files changed, 88 insertions(+), 89 deletions(-) diff --git a/.github/workflows/call-deploy-book.yml b/.github/workflows/call-deploy-book.yml index 43745e9..8a86e57 100644 --- a/.github/workflows/call-deploy-book.yml +++ b/.github/workflows/call-deploy-book.yml @@ -5,7 +5,7 @@ on: branches: - '**' # - '!dependabot**' - # If your git repository has the Jupyter Book within some-subfolder next to + # If your git repository has the TeachBooks / Jupyter Book v1 within some-subfolder next to # unrelated files, you can make this run only if a file within that specific # folder (or the workflow file itself) has been modified. # diff --git a/CITATION.cff b/CITATION.cff index 72d95e1..971b3d2 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -26,7 +26,7 @@ preferred-citation: value: 'https://github.com/TeachBooks/manual' description: 'GitHub repository' abstract: >- - his manual assists you in creating and collaborating on JupyterBooks + his manual assists you in creating and collaborating on TeachBooks for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start diff --git a/README.md b/README.md index bc19dcd..f70233d 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,14 @@ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15100848.svg)](https://doi.org/10.5281/zenodo.15100848) [![call-deploy-book](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml/badge.svg)](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml) -This manual assists you in creating and collaborating on [JupyterBooks](https://jupyterbook.org/v1/) for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start and advanced usages for new and existing users with or without skills on this topic. it is part of TeachBooks, for more information visit [https://teachbooks.io/](https://teachbooks.io/). +This manual assists you in creating and collaborating on TeachBooks: [JupyterBooks v1](https://jupyterbook.org/v1/) for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start and advanced usages for new and existing users with or without skills on this topic. it is part of TeachBooks, for more information visit [https://teachbooks.io/](https://teachbooks.io/). ## Contact If you encounter any issues and you have a TU Delft account, report it by clicking the github icon and lightbulb on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://github.com/Teachbooks/manual). If you have questions, contact the TeachBooks Development Team at info@teackbooks.io, also for non-TU Delft account holders. You can also contact us in our [GitHub discussions](https://github.com/orgs/TeachBooks/discussions) -We really value your feedback on this manual. This helps us improving it. Please keep using the manual as you build your own Jupyter Book and come back to fill out this short [survey](https://forms.gle/hXbFUQgN95H8ftxt9). +We really value your feedback on this manual. This helps us improving it. Please keep using the manual as you build your own TeachBooks and come back to fill out this short [survey](https://forms.gle/hXbFUQgN95H8ftxt9). ## Contribute This book will continue to develop, so feel free to contribute https://github.com/TeachBooks/manual! You can do so directly by forking this repository and creating a merge request. diff --git a/book/_toc.yml b/book/_toc.yml index 9ad0ef5..7a2e1c6 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -101,7 +101,7 @@ parts: sections: - file: external/annotater/README.md - file: basic-features/hypothesis.md - - caption: Original Jupyter Book and Sphinx Features + - caption: Original Jupyter Book v1 and Sphinx Features chapters: - file: basic-features/overview.md sections: diff --git a/book/basic-features/badges.md b/book/basic-features/badges.md index cc165d6..41cf07a 100644 --- a/book/basic-features/badges.md +++ b/book/basic-features/badges.md @@ -1,6 +1,6 @@ # Badges, Buttons & Icons -Jupyter book 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. +Jupyter book v1 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: @@ -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: Jupyter book provides a range of features which are visually appealing and functional. +Let's have a look at the first sentence of this chapter again: Jupyter book v1 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` ``` -Jupyter book provides a range of features which are visually appealing and functional. +Jupyter book v1 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 d9598bf..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/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 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 85ecac6..5036154 100644 --- a/book/basic-features/code.md +++ b/book/basic-features/code.md @@ -2,9 +2,9 @@ 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/v1/interactive/hiding.html?highlight=cell%20tag). Specifically, have a look at the sections on *hiding* cell inputs and *removing* cell inputs. diff --git a/book/basic-features/equations.md b/book/basic-features/equations.md index 5ec7a99..6223cc1 100644 --- a/book/basic-features/equations.md +++ b/book/basic-features/equations.md @@ -45,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/jupyterbook.md b/book/basic-features/jupyterbook.md index 12f9f2d..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/v1/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} diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index a89cb8d..74b4e04 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -7,4 +7,4 @@ This section is useful for [user type 3-5](../installation-and-setup/user_types. # Overview -These pages itemize some of the more common, basic book features which are all available in the original Jupyter book 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. +These pages itemize some of the more common, basic book features which are all available in the original Jupyter book v1 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/videos.md b/book/basic-features/videos.md index d623ad1..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 ```