From 816d78262620e6127b4bd2867b93cf1f645e8597 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 3 Nov 2025 13:58:19 +0100 Subject: [PATCH] Fix borken jupyterbook links --- README.md | 2 +- book/_static/figuurWidget.js | 2 +- book/basic-features/badges.md | 6 +++--- book/basic-features/banner.md | 2 +- book/basic-features/code.md | 4 ++-- book/basic-features/figures.md | 2 +- book/basic-features/jupyterbook.md | 2 +- book/basic-features/overview.md | 2 +- book/external/Sphinx-Grasple-public | 2 +- book/external/deploy-book-workflow | 2 +- book/external/template | 2 +- book/features/apa.md | 4 ++-- book/features/live_code.ipynb | 2 +- book/features/release_book_online.md | 2 +- book/features/teachbooks_intro.md | 2 +- book/installation-and-setup/collab.md | 2 +- book/installation-and-setup/jupyter-book-setup.md | 6 +++--- book/intro.md | 2 +- book/intro/book.md | 2 +- book/intro/workflow.md | 2 +- 20 files changed, 26 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 832a3c7..bc19dcd 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![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/) 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 [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/). ## 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). diff --git a/book/_static/figuurWidget.js b/book/_static/figuurWidget.js index e5801fd..64f9faa 100644 --- a/book/_static/figuurWidget.js +++ b/book/_static/figuurWidget.js @@ -255,7 +255,7 @@ const createFigureReference = (path, name, caption) => { + "{numref}`{number} <" + name + ">`"; } -//Via https://jupyterbook.org/en/stable/content/references.html#reference-tables +//Via https://jupyterbook.org/v1/content/references.html#reference-tables const createTableReference = (caption, name) => { return " tabel code:
" +"```{table} " + caption + "
" diff --git a/book/basic-features/badges.md b/book/basic-features/badges.md index 6fe1ad2..cc165d6 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 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 @@ -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 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 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..d9598bf 100644 --- a/book/basic-features/banner.md +++ b/book/basic-features/banner.md @@ -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 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: ``` sphinx: diff --git a/book/basic-features/code.md b/book/basic-features/code.md index 0b78694..85ecac6 100644 --- a/book/basic-features/code.md +++ b/book/basic-features/code.md @@ -6,9 +6,9 @@ Note that if you are using a `*.ipynb` file or including a code snippet in a `*. 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. -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/figures.md b/book/basic-features/figures.md index 97d82ee..3fecfae 100644 --- a/book/basic-features/figures.md +++ b/book/basic-features/figures.md @@ -39,7 +39,7 @@ 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: diff --git a/book/basic-features/jupyterbook.md b/book/basic-features/jupyterbook.md index 22dc777..12f9f2d 100644 --- a/book/basic-features/jupyterbook.md +++ b/book/basic-features/jupyterbook.md @@ -32,7 +32,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 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 eb75beb..a89cb8d 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 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/external/Sphinx-Grasple-public b/book/external/Sphinx-Grasple-public index 2ca3894..95a060e 160000 --- a/book/external/Sphinx-Grasple-public +++ b/book/external/Sphinx-Grasple-public @@ -1 +1 @@ -Subproject commit 2ca3894ef285f238cae1ba120ccf2c0f36e73b31 +Subproject commit 95a060e2dab5490a362c7f25a8b8954c6cd2aaa7 diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index 65010c7..2cb7fc3 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit 65010c7dc0eff87eb4d7729ee251d0df221c44f8 +Subproject commit 2cb7fc38e67d0aa486829027baee61d46c213e75 diff --git a/book/external/template b/book/external/template index 5183c16..1064963 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 5183c1616932c85a398e561124cf046288695101 +Subproject commit 1064963a9393a4a910d05435759887610d05bca5 diff --git a/book/features/apa.md b/book/features/apa.md index aad0ff9..5a4af37 100644 --- a/book/features/apa.md +++ b/book/features/apa.md @@ -85,7 +85,7 @@ Here are three examples for making citations: |`{cite:p}`| {cite:p}`jason_moore` | |`{cite}`| {cite}`jason_moore` | -For more options on the in-line citation style, see https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style. +For more options on the in-line citation style, see https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style. ### Known Issues @@ -97,7 +97,7 @@ Two issues are known: 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 features, [as described here](https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style), this extension implements the complete APA style, as well as enforcing round brackets (like this). The need to include a CSS file is an easy solution to the issue where empty brackets `[]` are left on the references page (to try it, simply delete `apastyle.css`). diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index 6674962..4b65144 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -95,7 +95,7 @@ "\n", "By `launch_buttons` you initiate the {fa}`rocket` --> {guilabel}`Live Code` on the top right corner of every page generated from a `.ipynb` file. \n", "\n", - "Note, if you're messing around with `html_theme_options` (for example when adding more buttons), all button behaviour is affected. In that case, as opposed to the jupyter book documentation, all buttons have to be specified from within `sphinx: html_theme_options` where you might also specify other buttons as well (ie. the [code repository button](https://jupyterbook.org/en/stable/basics/repository.html)).\n", + "Note, if you're messing around with `html_theme_options` (for example when adding more buttons), all button behaviour is affected. In that case, as opposed to the jupyter book documentation, all buttons have to be specified from within `sphinx: html_theme_options` where you might also specify other buttons as well (ie. the [code repository button](https://jupyterbook.org/v1/basics/repository.html)).\n", "\n", "```yaml\n", "sphinx:\n", diff --git a/book/features/release_book_online.md b/book/features/release_book_online.md index 98df709..527e8e9 100644 --- a/book/features/release_book_online.md +++ b/book/features/release_book_online.md @@ -118,7 +118,7 @@ One possible modification to this setup would be if you are progressively releas - Set `PRIMARY_BRANCH` to `2024` - Set `BEHAVIOR_PRIMARY` to `copy` -As your current students may then accidentally go to the older version of the book, we recommend you use a banner to indicate to readers that there is a (partial) new version available, and advise them where to find it. You can add a banner using this workflow (`BRANCHES_ARCHIVED`) or the [standard Jupyter Book banner feature](https://jupyterbook.org/en/stable/web/announcements.html). +As your current students may then accidentally go to the older version of the book, we recommend you use a banner to indicate to readers that there is a (partial) new version available, and advise them where to find it. You can add a banner using this workflow (`BRANCHES_ARCHIVED`) or the [standard Jupyter Book banner feature](https://jupyterbook.org/v1/web/announcements.html). ### Books with active editors working in parallel diff --git a/book/features/teachbooks_intro.md b/book/features/teachbooks_intro.md index b72a6b9..a08c35b 100644 --- a/book/features/teachbooks_intro.md +++ b/book/features/teachbooks_intro.md @@ -30,7 +30,7 @@ This section is useful for user type 4-5. The TeachBooks Python package is a collection of tools that are used to enhance the Jupyter Book software package by adding features and making customization easier. In general, it is only of interest to user types 4 and 5 when building a book locally. However, it may be important for other users to know what the package does, as it is incorporated in the [Deploy Book Workflow](../external/deploy-book-workflow/README.md) and, therefore, any book created from the [TeachBooks Template](../external/template/README.md). This raises two important points: 1. If you are a book user using the [TeachBooks Template](../external/template/README.md) and/or the [Deploy Book Workflow](../external/deploy-book-workflow/README.md), your book is by default built with the `teachbooks` package, and the way your book is built and features that are included in the book may change automatically when it is updated (these will be non-breaking changes; if not, we will notify our mailing list). -2. If you are using the `jupyter-book` package to build your book, some of the features described in this Manual may not be available to you (i.e., those listed on this page). This will be the case if you are using a [setup described in the Jupyter Book Manual](https://jupyterbook.org/en/stable/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/en/stable/publish/gh-pages.html). +2. If you are using the `jupyter-book` package to build your book, some of the features described in this Manual may not be available to you (i.e., those listed on this page). This will be the case if you are using a [setup described in the Jupyter Book Manual](https://jupyterbook.org/v1/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/v1/publish/gh-pages.html). For those who wish to use the package, it is available on [PyPI](https://pypi.org/project/teachbooks/) and can be installed using `pip install teachbooks`. As `teachbooks` is a wrapper, the package is meant to replace the usage of `jupyter-book` commands (although it does indeed add a few new commands to the CLI, e.g., `serve`). It is conventionally used in an identical way, as follows: diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md index 73ca862..c09090c 100644 --- a/book/installation-and-setup/collab.md +++ b/book/installation-and-setup/collab.md @@ -15,7 +15,7 @@ Finally, ensure that team members identify themselves according to the user type ## Review process Furthermore, establish a clear editing and review process. -For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency. Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [repository button {octicon}`mark-github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/en/stable/basics/repository.html) is advised. +For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency. Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [repository button {octicon}`mark-github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/v1/basics/repository.html) is advised. (draft_book)= ## Define draft version of book diff --git a/book/installation-and-setup/jupyter-book-setup.md b/book/installation-and-setup/jupyter-book-setup.md index 066c6d8..0c0fb97 100644 --- a/book/installation-and-setup/jupyter-book-setup.md +++ b/book/installation-and-setup/jupyter-book-setup.md @@ -7,9 +7,9 @@ This page is useful for user type 5. # Build your book: JupyterBook -Jupyter book is a regular Python package which converts our content into a website. It's part of all of the `requirements.txt` files for a book repository. At TeachBooks we developed a Python package called `teachbooks` which takes over the these features and adds [additional features](../features/overview.md). One of those additional features, for example, is the workflow to GitHub Pages. +Jupyter book is a regular Python package which converts our content into a website. It's part of all of the `requirements.txt` files for a book repository. At TeachBooks we developed a Python package called `teachbooks` which takes over the these features and adds [additional features](../features/overview.md). One of those additional features, for example, is the workflow to GitHub Pages. -Concretely, this means that the teachbooks package can be used to replace the Jupyter book package when calling these features. You could think of it as `jupyter-book` being a dependency of `teachbooks`. +Concretely, this means that the teachbooks package can be used to replace the Jupyter book package when calling these features. You could think of it as `jupyter-book` being a dependency of `teachbooks`. ```{admonition} Note :class: tip @@ -18,7 +18,7 @@ Don't forget to add the package `teachbooks` in the `requirements.txt` files in ## Build a book -As soon as you've installed your book environment with jupyter-book you can build your book locally. The official Jupyter book documentation is quite extensive. You can navigate to the directory where your book is to leave out the `path-to-book`. +As soon as you've installed your book environment with jupyter-book you can build your book locally. The official Jupyter book documentation is quite extensive. You can navigate to the directory where your book is to leave out the `path-to-book`. ``` teachbooks build diff --git a/book/intro.md b/book/intro.md index efef43c..325cb6d 100644 --- a/book/intro.md +++ b/book/intro.md @@ -1,6 +1,6 @@ # TeachBooks Manual -This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on Jupyter book. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users with many additional features developed for education-purposes. We hope you find this resource useful and refer back to it often. +This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on Jupyter book. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users with many additional features developed for education-purposes. We hope you find this resource useful and refer back to it often. TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our open source community beyond Delft and welcome contributions from all users. diff --git a/book/intro/book.md b/book/intro/book.md index d70bfb6..86b6b0b 100644 --- a/book/intro/book.md +++ b/book/intro/book.md @@ -6,7 +6,7 @@ Never seen a TeachBook before? Here's a small demo of the MUDE-book! :class: blend ``` -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. +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/v1/) 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 diff --git a/book/intro/workflow.md b/book/intro/workflow.md index bc0c038..a472ace 100644 --- a/book/intro/workflow.md +++ b/book/intro/workflow.md @@ -26,7 +26,7 @@ Let's create a space for you idea to form. You can create your own version of th width: 100px align: right ``` -Creativity activated, let's start adding content to your book! You'll add text, images, videos, math, interactive quizes, coding, widgets, etc. As editing the book is not directly done in a graphical interface with buttons like Microsoft Word, you'll need to learn a bit of syntax. The [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) will be added to your bookmarks. The changes you'll make have to be added to the GitHub version control system, creating `commits` on the your git `branch`. +Creativity activated, let's start adding content to your book! You'll add text, images, videos, math, interactive quizes, coding, widgets, etc. As editing the book is not directly done in a graphical interface with buttons like Microsoft Word, you'll need to learn a bit of syntax. The [MyST syntax cheat sheet](https://jupyterbook.org/v1/reference/cheatsheet.html) will be added to your bookmarks. The changes you'll make have to be added to the GitHub version control system, creating `commits` on the your git `branch`. ## 4 check changes ```{figure} figures/check.png