From 683a8f1bae75d8cc302629c782e978e14bedcc00 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Wed, 30 Apr 2025 23:06:18 +0200 Subject: [PATCH 001/109] Update 008.md --- book/syntax_exercises/008.md | 74 ++++++++++++++++++++++++++++++++---- 1 file changed, 67 insertions(+), 7 deletions(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index c363da7..7cbd25a 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -1,15 +1,18 @@ # Exercise 8: Add visual media -To help you illustrate your content, it can be useful to add some type of visual media such as figures or gifs. If you want to add a figure/gif to you book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale). +To help you illustrate your content, it can be useful to add some type of visual media such as figures, gifs or videos. If you want to add a figure/gif to your book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale). + ::::::{topic} Exercise objective -Can you add figures to your page? +Can you add figures and videos to your page? :::::: ```{note} Unless you are using a file format like `*.svg`, the raw contents of a visual media file typically are not human-readable or have a binary file format. This is not an ideal file type to use with Git. When just beginning to learn about all the tools associated with a TeachBook, we recommend you keep things simple and do whatever is easiest for you. Note, however, that as your book grows, especially if you use a lot of non-svg images, you may want to find a different way to store them (guidance will be provided on this soon in the TeachBooks Manual---stay tuned!). ``` +## Adding figures + 1. You will first need to upload your media to the repository. Navigate to the folder called figures (`book/figures`) and make sure you are in the right branch. On the right top, click on `Add file` - {octicon}`upload;1em` `Upload new file`. Note that you can store your files in another folder within the book directory too. However it's good practice to store figures in a separate folder (eventually per chapter). @@ -51,13 +54,69 @@ align: center ``` ```` -6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -7. Add a commit message. +## Adding videos -8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +7. You can also embed videos (e.g., from YouTube) into your book using the [`sphinx-iframes`](https://github.com/TeachBooks/sphinx-iframes) extension. Firstly the extension needs to be installed. If you're working locally, install the module using pip: + +```bash +pip install sphinx-iframes +``` + +8. After installation, add the package in your `requirements.txt` to track the dependency: + +``` +sphinx-iframes +``` + +9. Now the extension needs to be enabled. Do this by adding the extension to the list of Sphinx extra extensions in your `_config.yml` file (**important**: underscore, not dash): + +```yaml +sphinx: + extra_extensions: + . + . + . + - sphinx_iframes + . + . + . +``` + +10. You can also configure several values which can be added to `_config.yml`, such as default video sizes. Add the following: + +```yaml +sphinx: + config: + iframe_blend: true + iframe_width: calc(100% - 2.8rem) + iframe_aspectratio: auto 2 / 1 +``` + +11. Let's test out this extension! Use the `{video}` directive to embed a video. Here’s an example you can try using a public YouTube video: + +````md +```{video} https://www.youtube.com/watch?v=x2eonqw5M6o +:width: 80% +:height: 400px +:class: blend +``` +```` + +```{tip} +The blend class helps the video look good in dark mode! +``` + +12. Try to change the `width`and `height` of the video in the previous example to customise the display. + +13. When you're ready, commit your changes to the repository by clicking the green `Commit changes` button. + +14. Add a commit message. + +15. To see your changes, go to {octicon}`play;1em` `Actions` – The most recent workflow run (`overview.md` / your commit message) – Wait for it to finish – In the summary, click on the link under `Branches deployed` and under `Primary book at root`. + +16. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. -9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding :class: note @@ -67,5 +126,6 @@ Before moving on to the next exercise, make sure you understand the following: - What is the recommended practice for storing figures in the book directory? - What should you be cautious about when specifying the file extension of your figure? - How do you refer to a figure located in a different directory than your chapter? - +- What extension must be added to embed videos in the book? +``` ``` \ No newline at end of file From 7cdccf13a9faf54f7cd24248df183c30214f2fd0 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 1 May 2025 11:00:49 +0200 Subject: [PATCH 002/109] Create CODE_OF_CONDUCT.md --- CODE_OF_CONDUCT.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a174f8c --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,22 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this book, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, updating content, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality. + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery +- Personal attacks +- Trolling or insulting/derogatory comments +- Public or private harassment +- Publishing other’s private information, such as physical or electronic addresses, without explicit permission +- Other unethical or unprofessional conduct + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team. + +This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers. + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 1.2.0, available at [https://www.contributor-covenant.org/version/1/2/0/code-of-conduct.html](https://www.contributor-covenant.org/version/1/2/0/code-of-conduct.html) From 0c3eb7582668eaf7d9de36eb4d8891b75b5f8831 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 1 May 2025 12:20:17 +0200 Subject: [PATCH 003/109] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e2710af..fe12d18 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,6 @@ This tool's repository is stored on [GitHub](https://github.com/TeachBooks/templ ## Reuse content Feel free to reuse this content or contribute to it. Please give appropriate credit, provide a link to the license, and indicate if changes were made ([CC BY 4.0 License](https://creativecommons.org/licenses/by/4.0/)) -The website (http://oit.tudelft.nl/Macaulays-method/) is created using the [TeachBooks Python package](https://github.com/TeachBooks/TeachBooks). To recreate it you have two options (more information in the [TeachBooks manual](https://teachbooks.io/manual/): +The website (``) is created using the [TeachBooks Python package](https://github.com/TeachBooks/TeachBooks). To recreate it you have two options (more information in the [TeachBooks manual](https://teachbooks.io/manual/): - In the GitHub interface: fork this repository, enable Github Pages from the source GitHub actions (Settings - Code and automation - Pages - Build and deployment - Source - GitHub Actions), enable workflows (Actions - I understand my workflows, go ahead and enable them) and run the call-deploy-book workflow (Actions - call-deploy-book - Run workflow - Run workflow). The website is released on the URL as shown on the workflow summary when the workflow has finished (Actions - call-deploy-book - call-deploy-book - Summary). - On your own computer: clone this repository, install the required packages (`pip install -r requirements.txt`) and build the book (`teachbooks build book`). The website is stored locally in `book/_build/index.html`. From 32dbabff4d50065db63dadece2fabd478058dfb9 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sun, 4 May 2025 23:37:21 +0200 Subject: [PATCH 004/109] Update 008.md --- book/syntax_exercises/008.md | 56 ++++-------------------------------- 1 file changed, 6 insertions(+), 50 deletions(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index 7cbd25a..b29b68a 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -57,65 +57,21 @@ align: center ## Adding videos -7. You can also embed videos (e.g., from YouTube) into your book using the [`sphinx-iframes`](https://github.com/TeachBooks/sphinx-iframes) extension. Firstly the extension needs to be installed. If you're working locally, install the module using pip: +7. You can also embed videos (e.g., from YouTube) into your book using the [`sphinx-iframes`](https://github.com/TeachBooks/sphinx-iframes) extension, which is already part of the TeachBooks template. Try the example below using the `video` directive with a regular YouTube URL: -```bash -pip install sphinx-iframes -``` - -8. After installation, add the package in your `requirements.txt` to track the dependency: - -``` -sphinx-iframes -``` - -9. Now the extension needs to be enabled. Do this by adding the extension to the list of Sphinx extra extensions in your `_config.yml` file (**important**: underscore, not dash): - -```yaml -sphinx: - extra_extensions: - . - . - . - - sphinx_iframes - . - . - . -``` - -10. You can also configure several values which can be added to `_config.yml`, such as default video sizes. Add the following: - -```yaml -sphinx: - config: - iframe_blend: true - iframe_width: calc(100% - 2.8rem) - iframe_aspectratio: auto 2 / 1 -``` - -11. Let's test out this extension! Use the `{video}` directive to embed a video. Here’s an example you can try using a public YouTube video: ````md -```{video} https://www.youtube.com/watch?v=x2eonqw5M6o -:width: 80% -:height: 400px -:class: blend +```{video} https://www.youtube.com/watch/B1J6Ou4q8vE ``` ```` -```{tip} -The blend class helps the video look good in dark mode! -``` +8. When you're ready, commit your changes to the repository by clicking the green `Commit changes` button. -12. Try to change the `width`and `height` of the video in the previous example to customise the display. +9. Add a commit message. -13. When you're ready, commit your changes to the repository by clicking the green `Commit changes` button. +10. To see your changes, go to {octicon}`play;1em` `Actions` – The most recent workflow run (`overview.md` / your commit message) – Wait for it to finish – In the summary, click on the link under `Branches deployed` and under `Primary book at root`. -14. Add a commit message. - -15. To see your changes, go to {octicon}`play;1em` `Actions` – The most recent workflow run (`overview.md` / your commit message) – Wait for it to finish – In the summary, click on the link under `Branches deployed` and under `Primary book at root`. - -16. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding From 7f767329c17c29f3305fb9c3701e1255364f42d0 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sun, 4 May 2025 23:42:59 +0200 Subject: [PATCH 005/109] Update 008.md --- book/syntax_exercises/008.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index b29b68a..2ca453f 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -82,6 +82,4 @@ Before moving on to the next exercise, make sure you understand the following: - What is the recommended practice for storing figures in the book directory? - What should you be cautious about when specifying the file extension of your figure? - How do you refer to a figure located in a different directory than your chapter? -- What extension must be added to embed videos in the book? ``` -``` \ No newline at end of file From 4dda1b0e95e93ba05e01bd3213cb82cfae8003ba Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 13 May 2025 09:20:57 +0200 Subject: [PATCH 006/109] exercise 6 --- book/exercises/006.md | 112 +++++++++++++++++++++++++----------------- book/exercises/007.md | 53 ++++++++++++++++++++ 2 files changed, 119 insertions(+), 46 deletions(-) create mode 100644 book/exercises/007.md diff --git a/book/exercises/006.md b/book/exercises/006.md index 9287d06..3dda89f 100644 --- a/book/exercises/006.md +++ b/book/exercises/006.md @@ -1,53 +1,73 @@ -# Exercise 6: Contribute to the book of somebody else +# Exercise 6: Use pages from someone else's book + +So far, you've been working inside your own book. But what if someone else has already written a page that you'd like to reuse or refer to in your own book? Instead of copying the content manually, you can **link to their page directly** using [TeachBooks’ external content feature](https://teachbooks.io/manual/features/external_toc.html). This way, if the original page is updated, your book will reflect those changes automatically! + +\::::::{topic} Exercise objective +Can you include a page from someone else’s book into your own using the `external` keyword? +\:::::: + +1. Choose a book you want to reuse content from. For this exercise, you can use this one as an example: `https://github.com/TeachBooks/manual`. Browse its content to find a specific page (e.g. `intro.md`). +2. In your own book repository, open the `_toc.yml` file. This controls which pages are shown in your book and in what order. +3. To use the functionality, use the `external:` keyword in the `_toc.yml` file to include a file directly from the GitHub repository as follows: + +```yaml +format: jb-book +root: . + +parts: + - caption: ... + chapters: + - file: ... + . + . + . + - external: + . + . + . +``` + +4. Try out different kind of links. You can point to: +* A file on a branch (this pulls the most recent version on that branch): `external: https://github.com/TeachBooks/manual/blob/release/book/intro.md` +* A file at a specific commit (this takes the file during the state of a specific commit (06d67e8)): `external: https://github.com/TeachBooks/manual/blob/06d67e8a0110c94d9147ce07090656dedc7d0e64/README.md` +* A file from a tag (this locks the file to the version associated with a specific tag (v1.1.1)): `external: https://github.com/TeachBooks/manual/blob/v1.1.1/README.md` + + +5. Commit your changes and push them to your GitHub repository. +6. Open the book online (e.g. via GitHub Pages or the link in your repository's `Actions` > latest deploy) and check whether the external page appears correctly. +7. If the external page doesn't load or gives an error, double-check: + + * The link is a raw `.md` file on GitHub (not the preview or rendered page). + * You’ve committed and pushed the `_toc.yml` change. + + +\`\`\`{admonition} Example `_toc.yml` snippet + +```yaml +format: jb-book +root: intro + +chapters: + - file: 001 + - file: 002 + - external: + url: https://github.com/teachbooks-demos/book-collaboration/blob/main/004.md + title: Collaboration in GitHub + - file: 003 +``` + +```` ```{tip} -For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner. -``` - -So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. - -```{note} -The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. -``` - -::::::{topic} Exercise objective -Can you fork a book repository of someone else, make changes and contribute back? -:::::: - -```{tip} -This part describes how you can make a change in the book of someone else. -``` - -1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). -2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. -3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` -4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ -5. Check the changes in the online book. -6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. -7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. -8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. -9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. -10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! - -```{tip} -This part describes how you can accept the changes in your book made by someone else. -``` - -1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. -2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? -3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. -4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. -5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. - -Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. +You can use external pages from public GitHub repositories that are formatted as valid Markdown. Just remember: the content is *read-only*—you can’t directly edit the external page from your book! +```` ```{admonition} Check your understanding :class: note Before moving on, make sure you understand the following: -- What is a fork and how does it differ from a branch? -- Why is it important to create an issue before starting to work on a contribution? -- How do you create a pull request from a forked repository to the original repository? -- What should you include in the description of a pull request? -- How can you ensure that your friend is aware of your pull request? -``` \ No newline at end of file +- What is the difference between linking to an external page vs copying it into your own book? +- How do you use the `external:` keyword in `_toc.yml`? +- Why might it be useful to include a page from another book instead of rewriting it yourself? +- How can you make sure an external page link works properly? +``` diff --git a/book/exercises/007.md b/book/exercises/007.md new file mode 100644 index 0000000..94d9635 --- /dev/null +++ b/book/exercises/007.md @@ -0,0 +1,53 @@ +# Exercise 7: Contribute to the book of somebody else + +```{tip} +For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner. +``` + +So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. + +```{note} +The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. +``` + +::::::{topic} Exercise objective +Can you fork a book repository of someone else, make changes and contribute back? +:::::: + +```{tip} +This part describes how you can make a change in the book of someone else. +``` + +1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). +2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. +3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` +4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ +5. Check the changes in the online book. +6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. +7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. +8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. +9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. +10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! + +```{tip} +This part describes how you can accept the changes in your book made by someone else. +``` + +1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. +2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? +3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. +4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. +5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. + +Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you understand the following: +- What is a fork and how does it differ from a branch? +- Why is it important to create an issue before starting to work on a contribution? +- How do you create a pull request from a forked repository to the original repository? +- What should you include in the description of a pull request? +- How can you ensure that your friend is aware of your pull request? +``` \ No newline at end of file From 8808d2ff0957913be6e4cd40c7f04451d185948d Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 13 May 2025 09:24:23 +0200 Subject: [PATCH 007/109] Update _toc.yml --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index 23ac43c..19b9103 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -15,6 +15,7 @@ parts: - file: exercises/004.md - file: exercises/005.md - file: exercises/006.md + - file: exercises/007.md - file: exercises/summary - file: syntax_exercises.md sections: From 7478b4ccf843418971551c2fd6de32376d1633e7 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 13 May 2025 09:28:22 +0200 Subject: [PATCH 008/109] Update 006.md --- book/exercises/006.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/exercises/006.md b/book/exercises/006.md index 3dda89f..658738c 100644 --- a/book/exercises/006.md +++ b/book/exercises/006.md @@ -2,9 +2,9 @@ So far, you've been working inside your own book. But what if someone else has already written a page that you'd like to reuse or refer to in your own book? Instead of copying the content manually, you can **link to their page directly** using [TeachBooks’ external content feature](https://teachbooks.io/manual/features/external_toc.html). This way, if the original page is updated, your book will reflect those changes automatically! -\::::::{topic} Exercise objective +::::::{topic} Exercise objective Can you include a page from someone else’s book into your own using the `external` keyword? -\:::::: +:::::: 1. Choose a book you want to reuse content from. For this exercise, you can use this one as an example: `https://github.com/TeachBooks/manual`. Browse its content to find a specific page (e.g. `intro.md`). 2. In your own book repository, open the `_toc.yml` file. This controls which pages are shown in your book and in what order. @@ -41,7 +41,7 @@ parts: * You’ve committed and pushed the `_toc.yml` change. -\`\`\`{admonition} Example `_toc.yml` snippet +````{admonition} Example `_toc.yml` snippet ```yaml format: jb-book @@ -60,7 +60,7 @@ chapters: ```{tip} You can use external pages from public GitHub repositories that are formatted as valid Markdown. Just remember: the content is *read-only*—you can’t directly edit the external page from your book! -```` +``` ```{admonition} Check your understanding :class: note From 6d0eff1bc0f04ba7e37d12b860b22690770065a1 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 13 May 2025 09:37:45 +0200 Subject: [PATCH 009/109] Update 006.md --- book/exercises/006.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/book/exercises/006.md b/book/exercises/006.md index 658738c..1486188 100644 --- a/book/exercises/006.md +++ b/book/exercises/006.md @@ -41,8 +41,7 @@ parts: * You’ve committed and pushed the `_toc.yml` change. -````{admonition} Example `_toc.yml` snippet - +````{admonition} Example: TOC snippet ```yaml format: jb-book root: intro @@ -55,7 +54,6 @@ chapters: title: Collaboration in GitHub - file: 003 ``` - ```` ```{tip} From bada7e161c5e3d2a09a3a9a6c15602f5bd37b0bf Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 13 May 2025 10:48:59 +0200 Subject: [PATCH 010/109] restructure a bit Keep original urls --- book/_toc.yml | 2 +- book/exercises.md | 3 +- book/exercises/005a.md | 71 +++++++++++++++++++++++++ book/exercises/006.md | 108 ++++++++++++++++---------------------- book/exercises/007.md | 53 ------------------- book/exercises/summary.md | 6 +-- 6 files changed, 122 insertions(+), 121 deletions(-) create mode 100644 book/exercises/005a.md delete mode 100644 book/exercises/007.md diff --git a/book/_toc.yml b/book/_toc.yml index 19b9103..abecdbf 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -14,8 +14,8 @@ parts: - file: exercises/003.md - file: exercises/004.md - file: exercises/005.md + - file: exercises/005a.md - file: exercises/006.md - - file: exercises/007.md - file: exercises/summary - file: syntax_exercises.md sections: diff --git a/book/exercises.md b/book/exercises.md index 491c7a4..cca212a 100644 --- a/book/exercises.md +++ b/book/exercises.md @@ -9,7 +9,8 @@ Maybe you're already comfortable with Git, GitHub and the concept of using softw 3. Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer? 4. Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online? 5. Can you merge your branch into `main` with a pull request? -6. Can you fork someone else's repo, and suggest a change in a pull request? +6. Can you add read-only content from someone else without manually copying the source? +7. Can you fork someone else's repo, and suggest a change in a pull request? If something is not clear, dive into to the relevant exercise page. ``` diff --git a/book/exercises/005a.md b/book/exercises/005a.md new file mode 100644 index 0000000..1486188 --- /dev/null +++ b/book/exercises/005a.md @@ -0,0 +1,71 @@ +# Exercise 6: Use pages from someone else's book + +So far, you've been working inside your own book. But what if someone else has already written a page that you'd like to reuse or refer to in your own book? Instead of copying the content manually, you can **link to their page directly** using [TeachBooks’ external content feature](https://teachbooks.io/manual/features/external_toc.html). This way, if the original page is updated, your book will reflect those changes automatically! + +::::::{topic} Exercise objective +Can you include a page from someone else’s book into your own using the `external` keyword? +:::::: + +1. Choose a book you want to reuse content from. For this exercise, you can use this one as an example: `https://github.com/TeachBooks/manual`. Browse its content to find a specific page (e.g. `intro.md`). +2. In your own book repository, open the `_toc.yml` file. This controls which pages are shown in your book and in what order. +3. To use the functionality, use the `external:` keyword in the `_toc.yml` file to include a file directly from the GitHub repository as follows: + +```yaml +format: jb-book +root: . + +parts: + - caption: ... + chapters: + - file: ... + . + . + . + - external: + . + . + . +``` + +4. Try out different kind of links. You can point to: +* A file on a branch (this pulls the most recent version on that branch): `external: https://github.com/TeachBooks/manual/blob/release/book/intro.md` +* A file at a specific commit (this takes the file during the state of a specific commit (06d67e8)): `external: https://github.com/TeachBooks/manual/blob/06d67e8a0110c94d9147ce07090656dedc7d0e64/README.md` +* A file from a tag (this locks the file to the version associated with a specific tag (v1.1.1)): `external: https://github.com/TeachBooks/manual/blob/v1.1.1/README.md` + + +5. Commit your changes and push them to your GitHub repository. +6. Open the book online (e.g. via GitHub Pages or the link in your repository's `Actions` > latest deploy) and check whether the external page appears correctly. +7. If the external page doesn't load or gives an error, double-check: + + * The link is a raw `.md` file on GitHub (not the preview or rendered page). + * You’ve committed and pushed the `_toc.yml` change. + + +````{admonition} Example: TOC snippet +```yaml +format: jb-book +root: intro + +chapters: + - file: 001 + - file: 002 + - external: + url: https://github.com/teachbooks-demos/book-collaboration/blob/main/004.md + title: Collaboration in GitHub + - file: 003 +``` +```` + +```{tip} +You can use external pages from public GitHub repositories that are formatted as valid Markdown. Just remember: the content is *read-only*—you can’t directly edit the external page from your book! +``` + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you understand the following: +- What is the difference between linking to an external page vs copying it into your own book? +- How do you use the `external:` keyword in `_toc.yml`? +- Why might it be useful to include a page from another book instead of rewriting it yourself? +- How can you make sure an external page link works properly? +``` diff --git a/book/exercises/006.md b/book/exercises/006.md index 1486188..94d9635 100644 --- a/book/exercises/006.md +++ b/book/exercises/006.md @@ -1,71 +1,53 @@ -# Exercise 6: Use pages from someone else's book - -So far, you've been working inside your own book. But what if someone else has already written a page that you'd like to reuse or refer to in your own book? Instead of copying the content manually, you can **link to their page directly** using [TeachBooks’ external content feature](https://teachbooks.io/manual/features/external_toc.html). This way, if the original page is updated, your book will reflect those changes automatically! - -::::::{topic} Exercise objective -Can you include a page from someone else’s book into your own using the `external` keyword? -:::::: - -1. Choose a book you want to reuse content from. For this exercise, you can use this one as an example: `https://github.com/TeachBooks/manual`. Browse its content to find a specific page (e.g. `intro.md`). -2. In your own book repository, open the `_toc.yml` file. This controls which pages are shown in your book and in what order. -3. To use the functionality, use the `external:` keyword in the `_toc.yml` file to include a file directly from the GitHub repository as follows: - -```yaml -format: jb-book -root: . - -parts: - - caption: ... - chapters: - - file: ... - . - . - . - - external: - . - . - . -``` - -4. Try out different kind of links. You can point to: -* A file on a branch (this pulls the most recent version on that branch): `external: https://github.com/TeachBooks/manual/blob/release/book/intro.md` -* A file at a specific commit (this takes the file during the state of a specific commit (06d67e8)): `external: https://github.com/TeachBooks/manual/blob/06d67e8a0110c94d9147ce07090656dedc7d0e64/README.md` -* A file from a tag (this locks the file to the version associated with a specific tag (v1.1.1)): `external: https://github.com/TeachBooks/manual/blob/v1.1.1/README.md` - - -5. Commit your changes and push them to your GitHub repository. -6. Open the book online (e.g. via GitHub Pages or the link in your repository's `Actions` > latest deploy) and check whether the external page appears correctly. -7. If the external page doesn't load or gives an error, double-check: - - * The link is a raw `.md` file on GitHub (not the preview or rendered page). - * You’ve committed and pushed the `_toc.yml` change. - - -````{admonition} Example: TOC snippet -```yaml -format: jb-book -root: intro - -chapters: - - file: 001 - - file: 002 - - external: - url: https://github.com/teachbooks-demos/book-collaboration/blob/main/004.md - title: Collaboration in GitHub - - file: 003 -``` -```` +# Exercise 7: Contribute to the book of somebody else ```{tip} -You can use external pages from public GitHub repositories that are formatted as valid Markdown. Just remember: the content is *read-only*—you can’t directly edit the external page from your book! +For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner. ``` +So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. + +```{note} +The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. +``` + +::::::{topic} Exercise objective +Can you fork a book repository of someone else, make changes and contribute back? +:::::: + +```{tip} +This part describes how you can make a change in the book of someone else. +``` + +1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). +2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. +3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` +4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ +5. Check the changes in the online book. +6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. +7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. +8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. +9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. +10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! + +```{tip} +This part describes how you can accept the changes in your book made by someone else. +``` + +1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. +2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? +3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. +4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. +5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. + +Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. + ```{admonition} Check your understanding :class: note Before moving on, make sure you understand the following: -- What is the difference between linking to an external page vs copying it into your own book? -- How do you use the `external:` keyword in `_toc.yml`? -- Why might it be useful to include a page from another book instead of rewriting it yourself? -- How can you make sure an external page link works properly? -``` +- What is a fork and how does it differ from a branch? +- Why is it important to create an issue before starting to work on a contribution? +- How do you create a pull request from a forked repository to the original repository? +- What should you include in the description of a pull request? +- How can you ensure that your friend is aware of your pull request? +``` \ No newline at end of file diff --git a/book/exercises/007.md b/book/exercises/007.md deleted file mode 100644 index 94d9635..0000000 --- a/book/exercises/007.md +++ /dev/null @@ -1,53 +0,0 @@ -# Exercise 7: Contribute to the book of somebody else - -```{tip} -For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner. -``` - -So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. - -```{note} -The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. -``` - -::::::{topic} Exercise objective -Can you fork a book repository of someone else, make changes and contribute back? -:::::: - -```{tip} -This part describes how you can make a change in the book of someone else. -``` - -1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). -2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. -3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` -4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ -5. Check the changes in the online book. -6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. -7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. -8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. -9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. -10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! - -```{tip} -This part describes how you can accept the changes in your book made by someone else. -``` - -1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. -2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? -3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. -4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. -5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. - -Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. - -```{admonition} Check your understanding -:class: note - -Before moving on, make sure you understand the following: -- What is a fork and how does it differ from a branch? -- Why is it important to create an issue before starting to work on a contribution? -- How do you create a pull request from a forked repository to the original repository? -- What should you include in the description of a pull request? -- How can you ensure that your friend is aware of your pull request? -``` \ No newline at end of file diff --git a/book/exercises/summary.md b/book/exercises/summary.md index 25bc7d6..a166a9d 100644 --- a/book/exercises/summary.md +++ b/book/exercises/summary.md @@ -15,10 +15,10 @@ Here is how these exercises relate to the workflow. | :---: | :---: | :---: | :---: | | 1 | Get and idea | 4 | Create an issue | | 2 | Create _your_ version of the book | 4 | Create a branch | -| 3 | Edit the book | 1, 2, 3| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | -| 4 | Check changes online | 1, 2, 3 | Workflows and Actions Summary | +| 3 | Edit the book | 1, 2, 3, 6| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | +| 4 | Check changes online | 1, 2, 3, 6 | Workflows and Actions Summary | | 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready| -| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks | +| 6 | Submit for review | 5, 7 | Open and merge a Pull Request, from a branch or forks | ## Keep practicing From 0439c883b8f10844200cb749fd4a10e6475df7d7 Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 17:20:12 +0200 Subject: [PATCH 011/109] Update 005a.md --- book/exercises/005a.md | 146 ++++++++++++++++++++++++++--------------- 1 file changed, 92 insertions(+), 54 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 1486188..d75e2f0 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -1,71 +1,109 @@ -# Exercise 6: Use pages from someone else's book +# Exercise 6: Reuse content from another book -So far, you've been working inside your own book. But what if someone else has already written a page that you'd like to reuse or refer to in your own book? Instead of copying the content manually, you can **link to their page directly** using [TeachBooks’ external content feature](https://teachbooks.io/manual/features/external_toc.html). This way, if the original page is updated, your book will reflect those changes automatically! - -::::::{topic} Exercise objective -Can you include a page from someone else’s book into your own using the `external` keyword? -:::::: - -1. Choose a book you want to reuse content from. For this exercise, you can use this one as an example: `https://github.com/TeachBooks/manual`. Browse its content to find a specific page (e.g. `intro.md`). -2. In your own book repository, open the `_toc.yml` file. This controls which pages are shown in your book and in what order. -3. To use the functionality, use the `external:` keyword in the `_toc.yml` file to include a file directly from the GitHub repository as follows: - -```yaml -format: jb-book -root: . - -parts: - - caption: ... - chapters: - - file: ... - . - . - . - - external: - . - . - . -``` - -4. Try out different kind of links. You can point to: -* A file on a branch (this pulls the most recent version on that branch): `external: https://github.com/TeachBooks/manual/blob/release/book/intro.md` -* A file at a specific commit (this takes the file during the state of a specific commit (06d67e8)): `external: https://github.com/TeachBooks/manual/blob/06d67e8a0110c94d9147ce07090656dedc7d0e64/README.md` -* A file from a tag (this locks the file to the version associated with a specific tag (v1.1.1)): `external: https://github.com/TeachBooks/manual/blob/v1.1.1/README.md` +So far, you've been working inside your own book. But what if someone else has already written a page you’d like to reuse? Instead of copying it, you can **include it directly** into your own book using the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). -5. Commit your changes and push them to your GitHub repository. -6. Open the book online (e.g. via GitHub Pages or the link in your repository's `Actions` > latest deploy) and check whether the external page appears correctly. -7. If the external page doesn't load or gives an error, double-check: - * The link is a raw `.md` file on GitHub (not the preview or rendered page). - * You’ve committed and pushed the `_toc.yml` change. +\::::::{topic} Exercise objective +Can you include a page from someone else’s book into your own using the Recombiner? +\:::::: -````{admonition} Example: TOC snippet +1. Open the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). +2. Select the book and chapter(s) you want to reuse: + + * Click on the book (e.g., **TeachBooks Manual**). + * Browse the chapters and click the `+` button to select the ones you want (e.g., **Collaboration in GitHub**). +3. Click **Show how do it yourself instructions** +4. Follow the instructions provided: + + * Copy the external link (it will look something like this): + + ```yaml + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/workflows/collaboration.md + ``` + * Paste it into the `parts:` or `chapters:` section of your `_toc.yml` file in your book repository. + * Save the changes, commit, and push them. + +\::::::{admonition} Example: `_toc.yml` snippet + ```yaml format: jb-book root: intro chapters: - file: 001 - - file: 002 - - external: - url: https://github.com/teachbooks-demos/book-collaboration/blob/main/004.md - title: Collaboration in GitHub + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/workflows/collaboration.md - file: 003 ``` -```` -```{tip} -You can use external pages from public GitHub repositories that are formatted as valid Markdown. Just remember: the content is *read-only*—you can’t directly edit the external page from your book! -``` +\:::::: + +5. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +6. Add a commit message. + +7. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). + +8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + + + +\::::::{admonition} Check your understanding +\:class: note + +Before moving on, make sure you understand: + +* What is the benefit of linking to an external page instead of copying it? +* How does using the Recombiner simplify adding external content? + \:::::: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -```{admonition} Check your understanding -:class: note -Before moving on, make sure you understand the following: -- What is the difference between linking to an external page vs copying it into your own book? -- How do you use the `external:` keyword in `_toc.yml`? -- Why might it be useful to include a page from another book instead of rewriting it yourself? -- How can you make sure an external page link works properly? -``` From e42fd30d764374649fa29da0559b13cdead44606 Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 22:24:34 +0200 Subject: [PATCH 012/109] Update 005a.md --- book/exercises/005a.md | 93 +++++++++++------------------------------- 1 file changed, 24 insertions(+), 69 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index d75e2f0..9e49aa2 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -1,29 +1,33 @@ # Exercise 6: Reuse content from another book -So far, you've been working inside your own book. But what if someone else has already written a page you’d like to reuse? Instead of copying it, you can **include it directly** into your own book using the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). +So far, you've been working inside your own book. But what if someone else has already written a page you’d like to reuse? Instead of copying it, you can **include it directly** into your own book using the `external:` feature in your `_toc.yml`. +You can find the link to reuse in one of two ways: +* Use the [TeachBooks Recombiner](https://teachbooks.io/recombiner/) to select and copy the link. +* If the page isn't listed in the Recombiner, find the link manually in the GitHub repository. \::::::{topic} Exercise objective -Can you include a page from someone else’s book into your own using the Recombiner? +Can you include a page from someone else’s book into your own using `external:` in your `_toc.yml`? \:::::: -1. Open the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). -2. Select the book and chapter(s) you want to reuse: +1. **Find the page you want to reuse:** - * Click on the book (e.g., **TeachBooks Manual**). - * Browse the chapters and click the `+` button to select the ones you want (e.g., **Collaboration in GitHub**). -3. Click **Show how do it yourself instructions** -4. Follow the instructions provided: + * **Option 1:** Open the [TeachBooks Recombiner](https://teachbooks.io/recombiner/), select the book and chapter(s) you want to reuse, and click **Show how do it yourself instructions**. Copy the `external:` link provided. + * **Option 2:** If the page isn’t in the Recombiner, find it manually: - * Copy the external link (it will look something like this): + * Go to the repository (e.g., [TeachBooks Manual on GitHub](https://github.com/TeachBooks/manual)). + * Browse the files and find the `.md` page you want (e.g., `README.md`, `workflows/collaboration.md`). + * Copy the **raw link** in this format: - ```yaml - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/workflows/collaboration.md - ``` - * Paste it into the `parts:` or `chapters:` section of your `_toc.yml` file in your book repository. - * Save the changes, commit, and push them. + ```yaml + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md + ``` + +2. Add the `external:` link into the `parts:` or `chapters:` section of your `_toc.yml` file. + +3. Save the changes, commit, and push them. \::::::{admonition} Example: `_toc.yml` snippet @@ -33,19 +37,19 @@ root: intro chapters: - file: 001 - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/workflows/collaboration.md + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md - file: 003 ``` \:::::: -5. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -6. Add a commit message. +5. Add a commit message. -7. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +6. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). -8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. @@ -56,54 +60,5 @@ Before moving on, make sure you understand: * What is the benefit of linking to an external page instead of copying it? * How does using the Recombiner simplify adding external content? +* What can you do if a page isn’t in the Recombiner? \:::::: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - From 087f66fe61959f0afd67db9d2701fc5c1219bf31 Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 22:31:20 +0200 Subject: [PATCH 013/109] display updates --- book/exercises/005a.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 9e49aa2..684e4b4 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -7,19 +7,19 @@ You can find the link to reuse in one of two ways: * Use the [TeachBooks Recombiner](https://teachbooks.io/recombiner/) to select and copy the link. * If the page isn't listed in the Recombiner, find the link manually in the GitHub repository. -\::::::{topic} Exercise objective +::::::{topic} Exercise objective Can you include a page from someone else’s book into your own using `external:` in your `_toc.yml`? -\:::::: +:::::: -1. **Find the page you want to reuse:** +1. Find the page you want to reuse: - * **Option 1:** Open the [TeachBooks Recombiner](https://teachbooks.io/recombiner/), select the book and chapter(s) you want to reuse, and click **Show how do it yourself instructions**. Copy the `external:` link provided. - * **Option 2:** If the page isn’t in the Recombiner, find it manually: + * Option 1: Open the [TeachBooks Recombiner](https://teachbooks.io/recombiner/), select the book and chapter(s) you want to reuse, and click *Show how do it yourself instructions*. Copy the `external:` link provided. + * Option 2: If the page isn’t in the Recombiner, find it manually: * Go to the repository (e.g., [TeachBooks Manual on GitHub](https://github.com/TeachBooks/manual)). * Browse the files and find the `.md` page you want (e.g., `README.md`, `workflows/collaboration.md`). - * Copy the **raw link** in this format: + * Copy the raw link in this format: ```yaml - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md @@ -29,7 +29,7 @@ Can you include a page from someone else’s book into your own using `external: 3. Save the changes, commit, and push them. -\::::::{admonition} Example: `_toc.yml` snippet +````{admonition} Example: `_toc.yml` snippet ```yaml format: jb-book @@ -41,7 +41,7 @@ chapters: - file: 003 ``` -\:::::: +```` 4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. @@ -53,12 +53,12 @@ chapters: -\::::::{admonition} Check your understanding -\:class: note +```{admonition} Check your understanding +:class: note Before moving on, make sure you understand: * What is the benefit of linking to an external page instead of copying it? * How does using the Recombiner simplify adding external content? * What can you do if a page isn’t in the Recombiner? - \:::::: +``` From 024ae261a63d86cf4aa7b83d35906269c43d1b33 Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 22:38:34 +0200 Subject: [PATCH 014/109] display updates 2 --- book/exercises/005a.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 684e4b4..6a21222 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -29,7 +29,7 @@ Can you include a page from someone else’s book into your own using `external: 3. Save the changes, commit, and push them. -````{admonition} Example: `_toc.yml` snippet +```{admonition} Example: `_toc.yml` snippet ```yaml format: jb-book @@ -41,7 +41,7 @@ chapters: - file: 003 ``` -```` +``` 4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. @@ -62,3 +62,15 @@ Before moving on, make sure you understand: * How does using the Recombiner simplify adding external content? * What can you do if a page isn’t in the Recombiner? ``` + + + + + + + + + + + + From 76658764fa414e62d2b26d2f71d390d260b04a6e Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 22:42:53 +0200 Subject: [PATCH 015/109] display updates 3 --- book/exercises/005a.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 6a21222..588b0f2 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -29,19 +29,19 @@ Can you include a page from someone else’s book into your own using `external: 3. Save the changes, commit, and push them. -```{admonition} Example: `_toc.yml` snippet -```yaml -format: jb-book -root: intro +````{admonition} Example: `_toc.yml` snippet -chapters: - - file: 001 - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md - - file: 003 -``` + ```yaml + format: jb-book + root: intro -``` + chapters: + - file: 001 + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md + - file: 003 + ``` +```` 4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. From 1950fb6df2b8756cd1d03a5ebc212f0a51772199 Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 22:47:12 +0200 Subject: [PATCH 016/109] display updates 4 --- book/exercises/005a.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 588b0f2..355e9e2 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -30,7 +30,8 @@ Can you include a page from someone else’s book into your own using `external: 3. Save the changes, commit, and push them. -````{admonition} Example: `_toc.yml` snippet +````{admonition} Example + `_toc.yml` snippet: ```yaml format: jb-book From b5436bd8ff62b388e66be4342d30809511ed55ed Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 12 Jun 2025 12:56:48 +0200 Subject: [PATCH 017/109] external link with branch --- book/exercises/005a.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 355e9e2..06dcb19 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -22,7 +22,7 @@ Can you include a page from someone else’s book into your own using `external: * Copy the raw link in this format: ```yaml - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md + - external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md ``` 2. Add the `external:` link into the `parts:` or `chapters:` section of your `_toc.yml` file. @@ -39,7 +39,7 @@ Can you include a page from someone else’s book into your own using `external: chapters: - file: 001 - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md + - external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md - file: 003 ``` ```` From 0f6ba3dc46fe97e04ca190d07f348ac2da43dfec Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 17 Jun 2025 18:49:18 +0200 Subject: [PATCH 018/109] external page test --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index abecdbf..ffebe94 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -17,6 +17,7 @@ parts: - file: exercises/005a.md - file: exercises/006.md - file: exercises/summary + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/overview.md - file: syntax_exercises.md sections: - file: syntax_exercises/007.md From f9111b4916aa786e03f26df0a508d6406dc78506 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 17 Jun 2025 19:54:03 +0200 Subject: [PATCH 019/109] new step --- book/_toc.yml | 1 - book/exercises/005a.md | 8 ++++++++ book/figures/external_page_attribution.png | Bin 0 -> 6996 bytes 3 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 book/figures/external_page_attribution.png diff --git a/book/_toc.yml b/book/_toc.yml index ffebe94..abecdbf 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -17,7 +17,6 @@ parts: - file: exercises/005a.md - file: exercises/006.md - file: exercises/summary - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/overview.md - file: syntax_exercises.md sections: - file: syntax_exercises/007.md diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 06dcb19..f1de3f6 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -52,7 +52,15 @@ Can you include a page from someone else’s book into your own using `external: 7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +8. When viewing your book online, open the reused page. At the top, you should see an **attribution box**. This confirms the external content is working correctly and shows where it was sourced from. +```{figure} ..\figures\external_page_attribution.png +:name: external_page_attribution +:width: 100% +:alt: Attribution box shown at the top of an external page + +Attribution box that appears at the top of an external page. +``` ```{admonition} Check your understanding :class: note diff --git a/book/figures/external_page_attribution.png b/book/figures/external_page_attribution.png new file mode 100644 index 0000000000000000000000000000000000000000..86d82863ecaf2a3e4727e21b60f02fb7ffca8c39 GIT binary patch literal 6996 zcmbVxcTiJL^lt#^ARVM*P%v~*dhbm_Q+lt`yY!BtARyAaO4F}Yk=_Ztg(6*&P^3eM z^p?Dczj^<>nKy6V&fJ^ay`SAZXV30A=YICB9$1~6goy+I0FY~Hs2BhMcpTXOHbey2 z`|mFL9PAH{pMkm(plY0D8~bp_Sy4w30H{qNy|%^2J`;OunEC+#cOic-oB^*d4gdht zwx){WvmmSe58a47;K$WlJY*7;VtYFmB-Avf4}iVm>By z0tt#%;9#+hi%C-8P_VbRKet6P+z!)yf5N-jqNJn*;oJQA($K&Fi1SAB{Cq2j)eAj7 zu(eXqXE%&_Aj?i{`{$}J_n}gD3x=Q<;>0_ES{zHqmw`zQ@`YCR(=|@F$r^n+{ z6T}z47kPGMn=^^RZ}h|er4g#{bbZ9Rm?W!F_SXLaZDr9HAzABe{E*xCnu6>L1l-dX?&M>TD`XU?rO1TKP=rS0&?zpr6 zKckf)Xsv%(QC&K3&i~lptBageUkQeTp0)}X`;;)P1O?!=;p;Vc7GyE1-}FZN2HcJ}o%%*5$JIJ8X!#1mPguU=FPJD+AM4#LZY+%d|+kB zXH>hJ5xh<9lQM^g4w+u^N)E>A4WF9Dyq2uL7LVHUcyU%^A~IMyOE=9YsCA)og8( z3#Y=1@?iHXN;TaJ;Y4~F$b8|z{Lz%dMn^!8)afx-CSPa~4(6D}5Xl^e)kRR?Jor!z z@K;{o{>Tg=hx7Hb`6ZT%i}iQy{A{AM*DXYYh>q$qT+aja5*dQXJTRR}S&CxypyKJl z9?3*j==bl8c^P2n5C49r8}fFXmb<^b{#FSO8tg4!O|pyl=pFrrGpLO@u2HaU!YU#i zb`o?(S%_I+ebGUj?gaLHao0cUnxL|fmXLdYx>XN406XafB7LU<+{EM;eVu34TB(40GxG< z%hNA*E@n`_$n#MltE6}s)jzh1{8)R-aaXMz1d_Xg>N@_!Uo z8_UrBN*&&%+E>(3oPvjy?!|0&zc7}=k$CyAVK0iMERAH+qHvPq;!TfJwp(ZN_BRji zd#RW0KCdt&^GkV@M2DA|P~r^FC)MeJfkn6mj1h3Jnjhwk{nB z&cy2fiLG7*1Zc)UmQaNRYH~xL+4+UV#%-6}D7jU>7@8Q)Xo?MtO)V=gO ztTKpHM8djIIu*el3`#o0YFZhy#$V=ta7T^#FhpksC zQ0*QWtt_`@oJ^P3pi9E}QKJttej(++(7UB==%0-y=vjf&ec0%q@%u1MfauP z_igTgJ>qcnkFA`f=#xaUh9v6SR?ODWaR%?!nNEB`zv^ZA%AW=hWL zU(W*d_4Q55o)!Ye>$dE-9u7EV^#3>7|C897sEe?qXoV;RjwtBn+R8;1ps6x15q^Cv zxWA@aLVn?@1%h44v8NXzZW5$IPBGMwDfRam8QnEM&G#UG?{}79`>>$g6EsHhV%2gjNBTywBP_379g8jr_a#xN!q8Uy(FuC3<6z(14k-zv zDYPxlHgrHX4bkyCc>7(AA4tKoLN}A_4r}zuA{=PwPRHGTuPRyvIR&J36Lu|71lDpO zRbiguG>tq~)~XwqW}!!-{;A?w&x9vKCt*H@t(S8{^VPwE zq~wm(fN#IfOQeEI>p)T=Z@$Bye(ntKsz+cRcV162@5xfMtA%IeOG_`Q0}uz&G032) z?GW@GdGqhlXM)%|!f!+Q`gBK=Y~WtrcIVF<0kZjnMj=oOhNJXd^S=JKWQC1z7>oG@ zmkfmd`y7l-`}3Nr%Hm)^TFmoWAK-!)TsQTmw-&1~N;>$(96c9>P~hOn8Z9$Bs^*5- zsx9qmLE3x_7F?X&<2qc(ZjWqn8mGUG)2zlYMpZb^2?ahmcLn>+7HCzQdvyn*Se&7A zM}4rbO*fGa+r4A7cS8FI_L*?kP$#zHHe#{VkBkGYSgz;gUEWJ&-?C4C>xBr9ev#^bP$-5UPIVGofy4 zrjE99o}Hpkpcm=O8+lzEKaZ#llv;r1yWj`SvVL~AtZJWDyq#1SIc?OQb23PEqz?70 zWaJaLw-82GS9ZT`4K?NMJcG$<_mb%3OsKfqrWS9lI7L&cogy{<YGF^1+k5QCDD8lLsak}53sYh}iC z1jSI~Vjyqqbfe9}CKj#RV7Y9LNQzC2xNv_b5&P*vH{T8#9Qq{j!;24ZoIp35< z)v9!ZH6_Rj;l#f#53wo00BI*T$&r#X+7M4A7{_Foe`?Fs!ka{Wn2 z=A1>z#bo7&^t7+zG!V**o|_E9gCU5^#IqZ42247bX4zzE<%qvvT|oCVSO|U{Qda#y zdglS8ts?6}nKWC(oi^5(f^-}-Pap7^&i`_Ha98T1u7xNFq86t%<6Sm9yYS9CcQjXy zwt8C`g)3g_l?_hkb$hfoy}V^U9ly#gWpMubBCavB@9{Xw7b%b_Os~E(SZrR?DgAhw zX)sahtGJ|z4lFf!J#Q+Sr`>rljI(PLzuTi?TRFmuorbUb9mFCA%57AsU3&Jewo)|Q zB%exVvcbKaR8pVR(n&o)-B+YyjGI&tV%YDyot_ zfzRA666fj`MY1Zk>lo1}Fo}KJ!oFqe2WqIR+rG-Ffml$Nxs5dH z9YW# zW^%I8Z6&9sx=dpdymcAd%ErO`#aAp$kH`vZq{mCWcrGLbz-%2XC&Xc;XJj-awi_`& z1{-+r@_YOCSN4x>YAXdk2gOtH9X-bOLtkiZt;_ApvIIOzG7E%*WwHrMGa3+f4h++1 zva)hXnW8cWu&Ath%b&BeCWODT#qJ~6%36uz-S?99*flv?Y^Hd6qmL;%rKgSBL?hw> zK5V4%<4z4OPk{q*D#-;ptnf=+*iGG4zg>bdd(szOAn?Z zk?$7|z+a^u(C$uSwyep{$RjP~<}0GVtIPi4a*S(SQp#^$UVjusrZ)UMZCF>YAM08g z%M9a4Ma_?;q-w`xHzMxE4oq82+!1;sZATC+c5~^cUULwe0x$p4KkK!Ld8`^qMy}`FK${qT9VXn3}M zfWU_a!vzJd@OVK^p~vNh_dv#Dk4YXEpQ>-UYJKZW9ukWa zOt~X!wmmq(1 zOcWtv-PVyX>PRj#|4hq(c`$5ZtZRn=O$k*$=J%$)_oC$kjco}9UG=t7$V&5qbDTv9T2(w*;F=4f>xaQm$Pr z8B9~tf`>@m5ZREK+;3tWdGW8AFmu>VDRj-eu(I}ibwDZ4DTTN)e9zs?$g>I+Hk>$* zuAQbcqDsvh(P50*D{vO%@*KzR5OIFPjnC(rSKqn`o1|eD~Ra|Hdjt5D`nIdvx>=`a%AReTz_}(m8VMJ47eWj@yNm{)S6Hoh0H}EK#taj!BZFOUr&B=*Buzb;IBCJNLUo-qV zA@E#+v16=K|ICIzf@1vP*qA(_E`oK_z*O1Fw#$EjC+*!28~yf^yC%Y$5jDwKZ{3mD zZ@W{NiKnQ=b~_?FX66UN?Hs%=V0e0RyuXXIrgRLy&RY8zD$ix&%h9Zz}7*$_x-;`};Z0+7FLZ>zAIRwkbTHDO8(^X~eJl!~UJ|FM$Yr82{m1z!RO^i56 z4cF_f+?J`kChlOltGAjZSx<4nnUovv9j=fe9n@FMnwL6 ziGYFnAA-9lOk+X}pW>%pJq-l!>~8lpu<)JmoC+uV5tpU(wGF>drEj)>F61qIU`6+f zp-ga!SMDdm#D2;k$FS0Gtk^Kophl#eDX^bpzf-0qRetITHuhaIb&@=$*6bF+cTMe# zm6+;#dh#R(o87)UOGEEnp@K*c2@;`@{A9N=R?_>m_A%39W zg&o8O+?bdVhIVowxF!Bn_I{({ce4rsw zWJqFPFzZLFZ>^kN72{G~bq1XLJ7mb0u*4T8WKG5)>PGZ{4!ud_X#Y`4zkVr2$6vrR z6(ICsaaVZJ3g;w5WeUA)QE`{I?2n4lUi6zATTjAs>xGF;Aa`Az3ic!nps5O0sZz3u F`CpHvV-x@Y literal 0 HcmV?d00001 From 6701caf92b1195ece0f2e7b2e99ea7eb109e4a79 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 17 Jun 2025 20:03:27 +0200 Subject: [PATCH 020/109] update figure --- book/exercises/005a.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index f1de3f6..4822470 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -54,12 +54,12 @@ Can you include a page from someone else’s book into your own using `external: 8. When viewing your book online, open the reused page. At the top, you should see an **attribution box**. This confirms the external content is working correctly and shows where it was sourced from. -```{figure} ..\figures\external_page_attribution.png +```{figure} ../figures/external_page_attribution.png :name: external_page_attribution :width: 100% -:alt: Attribution box shown at the top of an external page +:alt: Example of attribution box shown at the top of an external page -Attribution box that appears at the top of an external page. +Example of attribution box at the top of an external page. ``` ```{admonition} Check your understanding From 237b43b56e17aab4a6192fca3f95fa3a2fee1c5a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 18 Jun 2025 13:20:02 +0200 Subject: [PATCH 021/109] link to external figure --- book/exercises/005a.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 4822470..b213bbc 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -54,7 +54,7 @@ Can you include a page from someone else’s book into your own using `external: 8. When viewing your book online, open the reused page. At the top, you should see an **attribution box**. This confirms the external content is working correctly and shows where it was sourced from. -```{figure} ../figures/external_page_attribution.png +```{figure} https://github.com/TeachBooks/template_figures/blob/main/external_page_attribution.png?raw=true :name: external_page_attribution :width: 100% :alt: Example of attribution box shown at the top of an external page From ac4e319dd5fb62b272d2983bf6b4b7be6baf1b94 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 18 Jun 2025 13:20:29 +0200 Subject: [PATCH 022/109] Delete book/figures/external_page_attribution.png --- book/figures/external_page_attribution.png | Bin 6996 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 book/figures/external_page_attribution.png diff --git a/book/figures/external_page_attribution.png b/book/figures/external_page_attribution.png deleted file mode 100644 index 86d82863ecaf2a3e4727e21b60f02fb7ffca8c39..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6996 zcmbVxcTiJL^lt#^ARVM*P%v~*dhbm_Q+lt`yY!BtARyAaO4F}Yk=_Ztg(6*&P^3eM z^p?Dczj^<>nKy6V&fJ^ay`SAZXV30A=YICB9$1~6goy+I0FY~Hs2BhMcpTXOHbey2 z`|mFL9PAH{pMkm(plY0D8~bp_Sy4w30H{qNy|%^2J`;OunEC+#cOic-oB^*d4gdht zwx){WvmmSe58a47;K$WlJY*7;VtYFmB-Avf4}iVm>By z0tt#%;9#+hi%C-8P_VbRKet6P+z!)yf5N-jqNJn*;oJQA($K&Fi1SAB{Cq2j)eAj7 zu(eXqXE%&_Aj?i{`{$}J_n}gD3x=Q<;>0_ES{zHqmw`zQ@`YCR(=|@F$r^n+{ z6T}z47kPGMn=^^RZ}h|er4g#{bbZ9Rm?W!F_SXLaZDr9HAzABe{E*xCnu6>L1l-dX?&M>TD`XU?rO1TKP=rS0&?zpr6 zKckf)Xsv%(QC&K3&i~lptBageUkQeTp0)}X`;;)P1O?!=;p;Vc7GyE1-}FZN2HcJ}o%%*5$JIJ8X!#1mPguU=FPJD+AM4#LZY+%d|+kB zXH>hJ5xh<9lQM^g4w+u^N)E>A4WF9Dyq2uL7LVHUcyU%^A~IMyOE=9YsCA)og8( z3#Y=1@?iHXN;TaJ;Y4~F$b8|z{Lz%dMn^!8)afx-CSPa~4(6D}5Xl^e)kRR?Jor!z z@K;{o{>Tg=hx7Hb`6ZT%i}iQy{A{AM*DXYYh>q$qT+aja5*dQXJTRR}S&CxypyKJl z9?3*j==bl8c^P2n5C49r8}fFXmb<^b{#FSO8tg4!O|pyl=pFrrGpLO@u2HaU!YU#i zb`o?(S%_I+ebGUj?gaLHao0cUnxL|fmXLdYx>XN406XafB7LU<+{EM;eVu34TB(40GxG< z%hNA*E@n`_$n#MltE6}s)jzh1{8)R-aaXMz1d_Xg>N@_!Uo z8_UrBN*&&%+E>(3oPvjy?!|0&zc7}=k$CyAVK0iMERAH+qHvPq;!TfJwp(ZN_BRji zd#RW0KCdt&^GkV@M2DA|P~r^FC)MeJfkn6mj1h3Jnjhwk{nB z&cy2fiLG7*1Zc)UmQaNRYH~xL+4+UV#%-6}D7jU>7@8Q)Xo?MtO)V=gO ztTKpHM8djIIu*el3`#o0YFZhy#$V=ta7T^#FhpksC zQ0*QWtt_`@oJ^P3pi9E}QKJttej(++(7UB==%0-y=vjf&ec0%q@%u1MfauP z_igTgJ>qcnkFA`f=#xaUh9v6SR?ODWaR%?!nNEB`zv^ZA%AW=hWL zU(W*d_4Q55o)!Ye>$dE-9u7EV^#3>7|C897sEe?qXoV;RjwtBn+R8;1ps6x15q^Cv zxWA@aLVn?@1%h44v8NXzZW5$IPBGMwDfRam8QnEM&G#UG?{}79`>>$g6EsHhV%2gjNBTywBP_379g8jr_a#xN!q8Uy(FuC3<6z(14k-zv zDYPxlHgrHX4bkyCc>7(AA4tKoLN}A_4r}zuA{=PwPRHGTuPRyvIR&J36Lu|71lDpO zRbiguG>tq~)~XwqW}!!-{;A?w&x9vKCt*H@t(S8{^VPwE zq~wm(fN#IfOQeEI>p)T=Z@$Bye(ntKsz+cRcV162@5xfMtA%IeOG_`Q0}uz&G032) z?GW@GdGqhlXM)%|!f!+Q`gBK=Y~WtrcIVF<0kZjnMj=oOhNJXd^S=JKWQC1z7>oG@ zmkfmd`y7l-`}3Nr%Hm)^TFmoWAK-!)TsQTmw-&1~N;>$(96c9>P~hOn8Z9$Bs^*5- zsx9qmLE3x_7F?X&<2qc(ZjWqn8mGUG)2zlYMpZb^2?ahmcLn>+7HCzQdvyn*Se&7A zM}4rbO*fGa+r4A7cS8FI_L*?kP$#zHHe#{VkBkGYSgz;gUEWJ&-?C4C>xBr9ev#^bP$-5UPIVGofy4 zrjE99o}Hpkpcm=O8+lzEKaZ#llv;r1yWj`SvVL~AtZJWDyq#1SIc?OQb23PEqz?70 zWaJaLw-82GS9ZT`4K?NMJcG$<_mb%3OsKfqrWS9lI7L&cogy{<YGF^1+k5QCDD8lLsak}53sYh}iC z1jSI~Vjyqqbfe9}CKj#RV7Y9LNQzC2xNv_b5&P*vH{T8#9Qq{j!;24ZoIp35< z)v9!ZH6_Rj;l#f#53wo00BI*T$&r#X+7M4A7{_Foe`?Fs!ka{Wn2 z=A1>z#bo7&^t7+zG!V**o|_E9gCU5^#IqZ42247bX4zzE<%qvvT|oCVSO|U{Qda#y zdglS8ts?6}nKWC(oi^5(f^-}-Pap7^&i`_Ha98T1u7xNFq86t%<6Sm9yYS9CcQjXy zwt8C`g)3g_l?_hkb$hfoy}V^U9ly#gWpMubBCavB@9{Xw7b%b_Os~E(SZrR?DgAhw zX)sahtGJ|z4lFf!J#Q+Sr`>rljI(PLzuTi?TRFmuorbUb9mFCA%57AsU3&Jewo)|Q zB%exVvcbKaR8pVR(n&o)-B+YyjGI&tV%YDyot_ zfzRA666fj`MY1Zk>lo1}Fo}KJ!oFqe2WqIR+rG-Ffml$Nxs5dH z9YW# zW^%I8Z6&9sx=dpdymcAd%ErO`#aAp$kH`vZq{mCWcrGLbz-%2XC&Xc;XJj-awi_`& z1{-+r@_YOCSN4x>YAXdk2gOtH9X-bOLtkiZt;_ApvIIOzG7E%*WwHrMGa3+f4h++1 zva)hXnW8cWu&Ath%b&BeCWODT#qJ~6%36uz-S?99*flv?Y^Hd6qmL;%rKgSBL?hw> zK5V4%<4z4OPk{q*D#-;ptnf=+*iGG4zg>bdd(szOAn?Z zk?$7|z+a^u(C$uSwyep{$RjP~<}0GVtIPi4a*S(SQp#^$UVjusrZ)UMZCF>YAM08g z%M9a4Ma_?;q-w`xHzMxE4oq82+!1;sZATC+c5~^cUULwe0x$p4KkK!Ld8`^qMy}`FK${qT9VXn3}M zfWU_a!vzJd@OVK^p~vNh_dv#Dk4YXEpQ>-UYJKZW9ukWa zOt~X!wmmq(1 zOcWtv-PVyX>PRj#|4hq(c`$5ZtZRn=O$k*$=J%$)_oC$kjco}9UG=t7$V&5qbDTv9T2(w*;F=4f>xaQm$Pr z8B9~tf`>@m5ZREK+;3tWdGW8AFmu>VDRj-eu(I}ibwDZ4DTTN)e9zs?$g>I+Hk>$* zuAQbcqDsvh(P50*D{vO%@*KzR5OIFPjnC(rSKqn`o1|eD~Ra|Hdjt5D`nIdvx>=`a%AReTz_}(m8VMJ47eWj@yNm{)S6Hoh0H}EK#taj!BZFOUr&B=*Buzb;IBCJNLUo-qV zA@E#+v16=K|ICIzf@1vP*qA(_E`oK_z*O1Fw#$EjC+*!28~yf^yC%Y$5jDwKZ{3mD zZ@W{NiKnQ=b~_?FX66UN?Hs%=V0e0RyuXXIrgRLy&RY8zD$ix&%h9Zz}7*$_x-;`};Z0+7FLZ>zAIRwkbTHDO8(^X~eJl!~UJ|FM$Yr82{m1z!RO^i56 z4cF_f+?J`kChlOltGAjZSx<4nnUovv9j=fe9n@FMnwL6 ziGYFnAA-9lOk+X}pW>%pJq-l!>~8lpu<)JmoC+uV5tpU(wGF>drEj)>F61qIU`6+f zp-ga!SMDdm#D2;k$FS0Gtk^Kophl#eDX^bpzf-0qRetITHuhaIb&@=$*6bF+cTMe# zm6+;#dh#R(o87)UOGEEnp@K*c2@;`@{A9N=R?_>m_A%39W zg&o8O+?bdVhIVowxF!Bn_I{({ce4rsw zWJqFPFzZLFZ>^kN72{G~bq1XLJ7mb0u*4T8WKG5)>PGZ{4!ud_X#Y`4zkVr2$6vrR z6(ICsaaVZJ3g;w5WeUA)QE`{I?2n4lUi6zATTjAs>xGF;Aa`Az3ic!nps5O0sZz3u F`CpHvV-x@Y From 45253e3c7e6448fb8bd3c1e130d45ee66016eb24 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 18 Jun 2025 13:23:29 +0200 Subject: [PATCH 023/109] Update 005a.md --- book/exercises/005a.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index b213bbc..e46cf3b 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -25,34 +25,34 @@ Can you include a page from someone else’s book into your own using `external: - external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md ``` -2. Add the `external:` link into the `parts:` or `chapters:` section of your `_toc.yml` file. +2. Add the `external:` link into `chapters:` section of your `_toc.yml` file. 3. Save the changes, commit, and push them. ````{admonition} Example - `_toc.yml` snippet: +`_toc.yml` snippet: - ```yaml - format: jb-book - root: intro +```yaml +format: jb-book +root: intro - chapters: +parts: + - caption: Contents + chapters: - file: 001 - external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md - file: 003 - ``` +``` ```` 4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. 5. Add a commit message. -6. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +6. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). -7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. - -8. When viewing your book online, open the reused page. At the top, you should see an **attribution box**. This confirms the external content is working correctly and shows where it was sourced from. +7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. Open the reused page. At the top, you should see an **attribution box**. This confirms the external content is working correctly and shows where it was sourced from. ```{figure} https://github.com/TeachBooks/template_figures/blob/main/external_page_attribution.png?raw=true :name: external_page_attribution From d4b45a308eb7f21c2353b09fd39b0e260fdd474f Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 27 Jun 2025 23:04:55 +0200 Subject: [PATCH 024/109] exercise 13 --- book/_toc.yml | 1 + book/syntax_exercises/013.md | 133 +++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 book/syntax_exercises/013.md diff --git a/book/_toc.yml b/book/_toc.yml index abecdbf..c3263ab 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -25,6 +25,7 @@ parts: - file: syntax_exercises/010.md - file: syntax_exercises/011.md - file: syntax_exercises/012.md + - file: syntax_exercises/013.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md new file mode 100644 index 0000000..5929d6c --- /dev/null +++ b/book/syntax_exercises/013.md @@ -0,0 +1,133 @@ +# Exercise 13: Adding a Bibliography + +In this exercise, you will learn how to add a bibliography to your book and how to include references to sources using different citation styles (e.g., numeric, author–year, or label-based). + +\::::::{topic} Exercise objective +Can you include references in your book using a bibliography file and cite them using different formats? +\:::::: + +```{tip} +Citing references properly gives credit to original authors and improves your writing. See the [JupyterBook guide on citations](https://jupyterbook.org/en/stable/content/citations.html) for full details. +``` + +## Adding a bibliography + +1. Open or create a Markdown file where you want to use references. + +2. Make sure a bibliography file exists in your project. The default format is `.bib`, which uses BibTeX syntax. You can create a file called `references.bib` in the root or relevant folder of your project. + +3. In the `references.bib` file, and add entries to reference like the examples below. + +``` +@book{knuth1984, + author = {Donald E. Knuth}, + title = {The TeXbook}, + year = {1984}, + publisher = {Addison-Wesley} +} + +@article{einstein1905, + author = {Einstein, Albert}, + title = {On the Electrodynamics of Moving Bodies}, + journal = {Annalen der Physik}, + year = {1905} +} +``` +4. Return to the Markdown file you are working on, and link the bibliography file using a **front matter header**. This should be placed at the very top of your file to automatically enable citations and bibliography rendering: + +```md +--- +bibliography: references.bib +--- +``` + +````{admonition} What is a front matter header? +:class: note + +A front matter header is a block of configuration settings written in YAML and placed at the very top of a Markdown file, enclosed between triple dashes `---`. It allows you to specify page-level options such as the title, tags, or the bibliography file to use. + +For example, the following tells Jupyter Book to use `references.bib` for any citations on that page: + +```yaml +--- +bibliography: references.bib +--- +``` +```` + + + +```{tip} +You can add this `bibliography:` key in `_config.yml` to make the reference file available to the whole book instead of just per page. +``` + +## Citing sources in different formats + +5. To cite a source in **numeric style** (default when using `unsrt`), use `[@key]`. Try the following example: + +```md +Einstein's paper on relativity changed physics [@einstein1905]. +``` + + +6. To cite a source in **author–year style**, change the style to `author-year` as shown below. Try this out and see how the citation from the previous step changes to the new formatting style. + +````md +```{bibliography} +:style: author-year +:filter: False +``` +```` + + +7. You can also write inline references using `@key`, which will automatically expand to author/year or number depending on the style. Try this out: + +```md +@einstein1905 describes special relativity... +``` + +8. You can also site **multiple references** by separating them with semicolons: + +```md +Several foundational works include [@einstein1905; @knuth1984]. +``` + + +## Rendering the bibliography + +9. At the bottom of the page (or wherever appropriate), include a `{bibliography}` directive to render the list of references: + +````md +```{bibliography} +:style: unsrt +``` +```` + +```{tip} +You can use `:style:` to choose different reference formats. Common options include: +- `unsrt` (numerical, unsorted) +- `plain` (numerical, sorted) +- `author-year` (author/date) +- `apa`, `ieee`, `nature` (other standard citation styles) +``` + +10. Ensure your `.bib` file is correctly formatted and that each key used in `@key` or `[@key]` matches an entry in that file. If a reference doesn’t show up, double-check the syntax or run the build process again. + +12. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +13. Add a commit message. + +14. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). + +15. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you understand: +- How to include and link a bibliography file. +- How to cite a reference using `@key` and `[@key]`. +- How to switch between citation styles like numeric or author–year. +- How to render the bibliography list at the bottom of a page. +``` From a7135c51b82c29592f5f3b839a9e3a9181a6a804 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 27 Jun 2025 23:09:43 +0200 Subject: [PATCH 025/109] small changes --- book/syntax_exercises/013.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 5929d6c..8f03cde 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -2,9 +2,9 @@ In this exercise, you will learn how to add a bibliography to your book and how to include references to sources using different citation styles (e.g., numeric, author–year, or label-based). -\::::::{topic} Exercise objective +::::::{topic} Exercise objective Can you include references in your book using a bibliography file and cite them using different formats? -\:::::: +:::::: ```{tip} Citing references properly gives credit to original authors and improves your writing. See the [JupyterBook guide on citations](https://jupyterbook.org/en/stable/content/citations.html) for full details. @@ -33,7 +33,7 @@ Citing references properly gives credit to original authors and improves your wr year = {1905} } ``` -4. Return to the Markdown file you are working on, and link the bibliography file using a **front matter header**. This should be placed at the very top of your file to automatically enable citations and bibliography rendering: +4. Return to the Markdown file you are working on, and link the bibliography file using a front matter header. This should be placed at the very top of your file to automatically enable citations and bibliography rendering: ```md --- @@ -63,14 +63,14 @@ You can add this `bibliography:` key in `_config.yml` to make the reference file ## Citing sources in different formats -5. To cite a source in **numeric style** (default when using `unsrt`), use `[@key]`. Try the following example: +5. To cite a source in numeric style (default when using `unsrt`), use `[@key]`. Try the following example: ```md Einstein's paper on relativity changed physics [@einstein1905]. ``` -6. To cite a source in **author–year style**, change the style to `author-year` as shown below. Try this out and see how the citation from the previous step changes to the new formatting style. +6. To cite a source in author–year style, change the style to `author-year` as shown below. Try this out and see how the citation from the previous step changes to the new formatting style. ````md ```{bibliography} @@ -86,7 +86,7 @@ Einstein's paper on relativity changed physics [@einstein1905]. @einstein1905 describes special relativity... ``` -8. You can also site **multiple references** by separating them with semicolons: +8. You can also site multiple references by separating them with semicolons: ```md Several foundational works include [@einstein1905; @knuth1984]. From 1721ff9a6246f613e377a9d6bc6dc94cede6a2db Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 27 Jun 2025 23:14:17 +0200 Subject: [PATCH 026/109] small changes 2 --- book/syntax_exercises/013.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 8f03cde..712af49 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -45,14 +45,6 @@ bibliography: references.bib :class: note A front matter header is a block of configuration settings written in YAML and placed at the very top of a Markdown file, enclosed between triple dashes `---`. It allows you to specify page-level options such as the title, tags, or the bibliography file to use. - -For example, the following tells Jupyter Book to use `references.bib` for any citations on that page: - -```yaml ---- -bibliography: references.bib ---- -``` ```` From 487a436c57d638e40fc648fc01281b26c0010b80 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 1 Jul 2025 15:35:43 +0200 Subject: [PATCH 027/109] Update 013.md --- book/syntax_exercises/013.md | 192 ++++++++++++++++++++++------------- 1 file changed, 123 insertions(+), 69 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 712af49..a946c31 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -1,125 +1,179 @@ + # Exercise 13: Adding a Bibliography -In this exercise, you will learn how to add a bibliography to your book and how to include references to sources using different citation styles (e.g., numeric, author–year, or label-based). +In this exercise, you will learn how to cite sources using the shared bibliography provided in this template, and how to control the citation style and reference formatting using `{cite}` roles and the `{bibliography}` directive. ::::::{topic} Exercise objective -Can you include references in your book using a bibliography file and cite them using different formats? +Can you cite references using different in-line styles and customise the way your bibliography appears? :::::: ```{tip} Citing references properly gives credit to original authors and improves your writing. See the [JupyterBook guide on citations](https://jupyterbook.org/en/stable/content/citations.html) for full details. -``` - -## Adding a bibliography - -1. Open or create a Markdown file where you want to use references. - -2. Make sure a bibliography file exists in your project. The default format is `.bib`, which uses BibTeX syntax. You can create a file called `references.bib` in the root or relevant folder of your project. - -3. In the `references.bib` file, and add entries to reference like the examples below. - -``` -@book{knuth1984, - author = {Donald E. Knuth}, - title = {The TeXbook}, - year = {1984}, - publisher = {Addison-Wesley} -} - -@article{einstein1905, - author = {Einstein, Albert}, - title = {On the Electrodynamics of Moving Bodies}, - journal = {Annalen der Physik}, - year = {1905} -} -``` -4. Return to the Markdown file you are working on, and link the bibliography file using a front matter header. This should be placed at the very top of your file to automatically enable citations and bibliography rendering: - -```md ---- -bibliography: references.bib ---- -``` - -````{admonition} What is a front matter header? -:class: note - -A front matter header is a block of configuration settings written in YAML and placed at the very top of a Markdown file, enclosed between triple dashes `---`. It allows you to specify page-level options such as the title, tags, or the bibliography file to use. ```` +## Adding an entry to the shared bibliography +1. The TeachBooks template already includes a shared bibliography file (`references.bib`). Locate and open the file. You will see the following example entry: + +``` +@misc{jason_moore, + title={Learn Multibody Dynamics, SymPy}, + author={Moore, Jason}, + howpublished={\url{https://moorepants.github.io/learn-multibody-dynamics/sympy.html}}, + year={2023} +} +``` + +2. Add a new reference of your own. You can use a DOI, book title, or URL. ```{tip} -You can add this `bibliography:` key in `_config.yml` to make the reference file available to the whole book instead of just per page. +You can generate BibTeX entries using free tools like [ZoteroBib](https://zbib.org). Paste a source URL or title, click **Cite**, and export as **BibTeX** to copy into `references.bib`. ``` -## Citing sources in different formats +## Citing sources using `{cite}` -5. To cite a source in numeric style (default when using `unsrt`), use `[@key]`. Try the following example: +3. To reference a source in-line, use one of the `{cite}` roles. Try the following: ```md -Einstein's paper on relativity changed physics [@einstein1905]. +{cite:p}`jason_moore` ``` +4. You can also use other variants of `{cite}` depending on the style you want. Try adding the following to your Markdown file and see how the output differs: -6. To cite a source in author–year style, change the style to `author-year` as shown below. Try this out and see how the citation from the previous step changes to the new formatting style. +* `{cite:p}` +* `{cite:t}` +* `{cite:ps}` +* `{cite:ts}` + +```{dropdown} Hint: What to expect when you render these +:class: hint + +Here’s how the citation will appear for the example in the shared bibliography: + +- `{cite:p}` → **Parenthetical citation** + → [Moore, 2023] + +- `{cite:t}` → **Textual citation** + → Moore [2023] + +- `{cite:ps}` → **Parenthetical, full authors** + → [Moore, 2023] + +- `{cite:ts}` → **Textual, full authors** + → Moore [2023] + +> You can experiment with different reference styles in your `_config.yml` file to change how these look. +``` + +## Displaying the bibliography + +5. To show the list of cited references at the end of the page, use the `{bibliography}` directive: ````md ```{bibliography} -:style: author-year -:filter: False ``` ```` -7. You can also write inline references using `@key`, which will automatically expand to author/year or number depending on the style. Try this out: -```md -@einstein1905 describes special relativity... +`````{admonition} Avoiding duplicate citation warnings +:class: note + +If you use `{bibliography}` in multiple files, you might see warnings about duplicate citations when building your book. To avoid this, restrict the bibliography to only show references cited in the current page by adding a `:filter:` option: + +````md +```{bibliography} +:filter: docname in docnames ``` -8. You can also site multiple references by separating them with semicolons: +```` -```md -Several foundational works include [@einstein1905; @knuth1984]. +This ensures only local references are shown, and avoids build-time warnings. +````` + + +## Customising citation styles + + +6. You can change the **reference style** (how citations appear in your text) by editing the `_config.yml` file in your book folder. Add or modify the following section, and see how the referece style changes. + +```yaml +sphinx: + config: + bibtex_reference_style: author_year ``` +7. Try replacing `author_year` with the following and see how the citation outputs change: -## Rendering the bibliography +* `author_year` +* `label` +* `super` +* `number` -9. At the bottom of the page (or wherever appropriate), include a `{bibliography}` directive to render the list of references: +```{dropdown} Hint: What each reference style will look like +:class: hint + +Heres's how each style will appear for the example in the shared bibliography: + +- `author_year` → Moore (2023) +- `label` → [jason_moore] +- `super` → ¹ +- `number` → [1] + +``` + +8. You can also change the **bibliography style** (how the reference list is formatted) using the `:style:` option in the `{bibliography}` directive. Try replacing the style with the following, and see how the bibliography style changes. ````md ```{bibliography} :style: unsrt ``` + ```` -```{tip} -You can use `:style:` to choose different reference formats. Common options include: -- `unsrt` (numerical, unsorted) -- `plain` (numerical, sorted) -- `author-year` (author/date) -- `apa`, `ieee`, `nature` (other standard citation styles) +9. Experiment with the following different styles, and see how the bibliography style changes: + +- `alpha` +- `plain` +- `unsrt` +- `unsrtalpha` + +```{dropdown} Hint: What each bibliography style looks like +:class: hint + +Heres's how each style will appear for the example in the shared bibliography: + +- `alpha` → References labelled as [Knu84], sorted by author/year +- `plain` → References numbered [1], sorted by author/year +- `unsrt` → Numbered [1], in order of appearance in the text +- `unsrtalpha` → Alphanumeric like [Knu84], but in order of appearance + ``` -10. Ensure your `.bib` file is correctly formatted and that each key used in `@key` or `[@key]` matches an entry in that file. If a reference doesn’t show up, double-check the syntax or run the build process again. -12. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +```{admonition} Bibliography style vs. Reference style +:class: note -13. Add a commit message. +- **Reference style** controls how citations look in your text (e.g., [1] vs. (Author, Year)). +- **Bibliography style** controls how the reference list is formatted (e.g., sorted, numbered, APA). +``` -14. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +10. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -15. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +11. Add a commit message. + +12. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). + +13. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding :class: note Before moving on, make sure you understand: -- How to include and link a bibliography file. -- How to cite a reference using `@key` and `[@key]`. -- How to switch between citation styles like numeric or author–year. -- How to render the bibliography list at the bottom of a page. +- How to add a new reference to the shared `references.bib` file. +- How to use `{cite}` roles to control in-line citation appearance. +- How to change the citation style in `_config.yml`. +- How to display the bibliography with `{bibliography}`. ``` + From 46ee078f7e928b4a0315bf29e06fb04e4706a91d Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 1 Jul 2025 15:51:08 +0200 Subject: [PATCH 028/109] small changes --- book/syntax_exercises/013.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index a946c31..a097424 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -62,7 +62,6 @@ Here’s how the citation will appear for the example in the shared bibliography - `{cite:ts}` → **Textual, full authors** → Moore [2023] -> You can experiment with different reference styles in your `_config.yml` file to change how these look. ``` ## Displaying the bibliography @@ -77,7 +76,7 @@ Here’s how the citation will appear for the example in the shared bibliography `````{admonition} Avoiding duplicate citation warnings -:class: note +:class: warning If you use `{bibliography}` in multiple files, you might see warnings about duplicate citations when building your book. To avoid this, restrict the bibliography to only show references cited in the current page by adding a `:filter:` option: From fc439eca9cf670c18dd4f519b5ed2a93f17a2418 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 2 Jul 2025 07:42:13 +0200 Subject: [PATCH 029/109] Update 013.md --- book/syntax_exercises/013.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index a097424..3cadb1a 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -66,15 +66,13 @@ Here’s how the citation will appear for the example in the shared bibliography ## Displaying the bibliography -5. To show the list of cited references at the end of the page, use the `{bibliography}` directive: +5. To show the list of cited references at the end of the page, use the `{bibliography}` directive. In this template, the bibliography is already added to the [page](../references.md): ````md ```{bibliography} ``` ```` - - `````{admonition} Avoiding duplicate citation warnings :class: warning From 01cbcf48b2676b2f773624321208ee41edb4aa2e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 2 Jul 2025 07:44:30 +0200 Subject: [PATCH 030/109] Update 013.md --- book/syntax_exercises/013.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 3cadb1a..62db026 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -117,6 +117,8 @@ Heres's how each style will appear for the example in the shared bibliography: - `super` → ¹ - `number` → [1] +Feeling brave? You can also use APA references, although this is not a default option. More information on to set this up is available in the [TeachBooks manual](https://teachbooks.io/manual/features/apa.html) + ``` 8. You can also change the **bibliography style** (how the reference list is formatted) using the `:style:` option in the `{bibliography}` directive. Try replacing the style with the following, and see how the bibliography style changes. From 9c6e00017ae053afdcb51af00030413f2525d382 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 3 Jul 2025 08:50:56 +0200 Subject: [PATCH 031/109] Update requirements.txt --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index fc577ed..1b54e4f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,6 +7,7 @@ sphinx-exercise teachbooks-sphinx-tippy sphinx-iframes sphinx-named-colors +sphinx-dropdown-toggle # Now list the packages you want to download directly from GitHub git+https://github.com/TeachBooks/Sphinx-Thebe From 1729b0d278fecbc032356e56ed380c200409da52 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 3 Jul 2025 08:51:38 +0200 Subject: [PATCH 032/109] Update _config.yml --- book/_config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_config.yml b/book/_config.yml index 8fbad43..d7032eb 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -47,6 +47,7 @@ sphinx: # Options passed on to the - sphinx_exercise # Allows you to add exercise boxes to your book https://ebp-sphinx-exercise.readthedocs.io/en/latest/ - teachbooks_sphinx_tippy # Enables hoover over tips https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html - sphinx_named_colors # Allows you to use custom colors in your book https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html + - sphinx_dropdown_toggle # Adds a button to toggle all dropdowns with one click bibtex_bibfiles: - references.bib # Required for references From f7db33d333df197bc606cab95c1af6e009c7c8c0 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 19 Jul 2025 13:49:05 +0200 Subject: [PATCH 033/109] Create 007.md --- book/exercises/007.md | 67 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 book/exercises/007.md diff --git a/book/exercises/007.md b/book/exercises/007.md new file mode 100644 index 0000000..92bc525 --- /dev/null +++ b/book/exercises/007.md @@ -0,0 +1,67 @@ +# Exercise 8: Add extensions to your book + +TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels. + +\::::::{topic} Exercise objective +Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` in your TeachBooks book? +\:::::: + +1. In your book repository, open the `requirements.txt` file. This file lists the Python packages that will be installed to build your book. + +2. Add the following line to the bottom of the `requirements.txt` file: + + ``` + git+https://github.com/TeachBooks/Sphinx-Indexed-Definitions.git + ``` + + This tells the build system to install the extension directly from GitHub. + +3. Next, open `_config.yml` and add the extension to your `sphinx` configuration block: + + ```yaml + sphinx: + extra_extensions: + - indexed_definitions + ``` + + This ensures Sphinx loads the extension when building your book. + +4. Now you can use the new directive provided by the extension. Try adding the following to one of your Markdown files in the `book/` directory: + + `````md + ````{definition} Term + :label: term-definition + A word or phrase used to describe a concept or object. + ````` + + This will render a labelled, indexed definition that you can refer to from other parts of your book. + +5. Try to reference the definition in another file using `{ref}` followed by the given label, as shown below: + + + ```md + For more details, see the definition of {ref}`term-definition`. + ``` + + This will appear as a hyperlink that takes the reader directly to the definition. + +6. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. + + +7. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +8. Add a commit message. + +9. To see your changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you understand: + +* How do you add a new extension to a TeachBooks book? +* What is the purpose of the `requirements.txt` and `_config.yml` files? +* How can you confirm that your extension is working correctly? +``` From 5bf79adc0b252dd7ed49f84ef080fd57f4737943 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 19 Jul 2025 13:52:48 +0200 Subject: [PATCH 034/109] Update _toc.yml --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index c3263ab..e93a13f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -16,6 +16,7 @@ parts: - file: exercises/005.md - file: exercises/005a.md - file: exercises/006.md + - file: exercises/007.md - file: exercises/summary - file: syntax_exercises.md sections: From 71b50414fa2a0013078b9ae4a83b8f6a7a608410 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 19 Jul 2025 13:58:21 +0200 Subject: [PATCH 035/109] Update 007.md --- book/exercises/007.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/exercises/007.md b/book/exercises/007.md index 92bc525..0336bd1 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -2,9 +2,9 @@ TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels. -\::::::{topic} Exercise objective +::::::{topic} Exercise objective Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` in your TeachBooks book? -\:::::: +:::::: 1. In your book repository, open the `requirements.txt` file. This file lists the Python packages that will be installed to build your book. From 11e56e836e0a1c04fa64ddb8962b6cfd81a6ee4e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Jul 2025 10:37:32 +0200 Subject: [PATCH 036/109] Update 007.md --- book/exercises/007.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/book/exercises/007.md b/book/exercises/007.md index 0336bd1..d7b5256 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -1,6 +1,6 @@ # Exercise 8: Add extensions to your book -TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels. +TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels in an easy way. ::::::{topic} Exercise objective Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` in your TeachBooks book? @@ -11,10 +11,10 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` 2. Add the following line to the bottom of the `requirements.txt` file: ``` - git+https://github.com/TeachBooks/Sphinx-Indexed-Definitions.git + sphinx-indexed-definitions ``` - This tells the build system to install the extension directly from GitHub. + This tells the build system to install the extension from PyPi, a repository which contains Python software 3. Next, open `_config.yml` and add the extension to your `sphinx` configuration block: @@ -26,7 +26,9 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` This ensures Sphinx loads the extension when building your book. -4. Now you can use the new directive provided by the extension. Try adding the following to one of your Markdown files in the `book/` directory: +4. Now you can use the new directive provided by the extension. First, read the documentation to understand how to apply it. In most cases, the documentation can be found in the README of the source repository of the software. For our example that is here: https://github.com/TeachBooks/Sphinx-Indexed-Definitions + +5. Try adding the following to one of your Markdown files in the `book/` directory: `````md ````{definition} Term @@ -36,7 +38,7 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` This will render a labelled, indexed definition that you can refer to from other parts of your book. -5. Try to reference the definition in another file using `{ref}` followed by the given label, as shown below: +6. Try to reference the definition in another file using `{ref}` followed by the given label, as shown below: ```md @@ -45,15 +47,14 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` This will appear as a hyperlink that takes the reader directly to the definition. -6. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. +7. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. Check out the ever-growing list of TeachBooks extensions in the [TeachBooks manual](https://teachbooks.io/manual/features/overview.html)! +8. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -7. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +9. Add a commit message. -8. Add a commit message. - -9. To see your changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). -10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +10. To see your changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding From 1096b93dbd96fc68263e92a6e286f4fbd27120a9 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 29 Jul 2025 07:18:34 +0200 Subject: [PATCH 037/109] Update call-deploy-book.yml --- .github/workflows/call-deploy-book.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/call-deploy-book.yml b/.github/workflows/call-deploy-book.yml index 2cdfefd..6bcf1b7 100644 --- a/.github/workflows/call-deploy-book.yml +++ b/.github/workflows/call-deploy-book.yml @@ -16,7 +16,7 @@ on: jobs: call-workflow: - uses: TeachBooks/deploy-book-workflow/.github/workflows/deploy-book.yml@main + uses: TeachBooks/deploy-book-workflow/.github/workflows/deploy-book.yml@v1.0.0 secrets: inherit permissions: contents: read From 06992f07119e7f7c6c11a0deadf3530e6617e46b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 29 Jul 2025 07:19:42 +0200 Subject: [PATCH 038/109] Update call-deploy-book.yml --- .github/workflows/call-deploy-book.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/call-deploy-book.yml b/.github/workflows/call-deploy-book.yml index 6bcf1b7..76ccb8d 100644 --- a/.github/workflows/call-deploy-book.yml +++ b/.github/workflows/call-deploy-book.yml @@ -16,7 +16,7 @@ on: jobs: call-workflow: - uses: TeachBooks/deploy-book-workflow/.github/workflows/deploy-book.yml@v1.0.0 + uses: TeachBooks/deploy-book-workflow/.github/workflows/deploy-book.yml@v1 secrets: inherit permissions: contents: read From a8cc696303ced92db93ba7fc15f37edc47ed2742 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 30 Jul 2025 14:19:28 +0200 Subject: [PATCH 039/109] Create CODEOWNERS --- CODEOWNERS | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 CODEOWNERS diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..e5d7b22 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,2 @@ +# All files in the repo +* @Tom-van-Woudenberg From 49d539b5bf97b24e7d8962a6cb31d5ef9dbf717e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 31 Jul 2025 08:11:42 +0200 Subject: [PATCH 040/109] Update requirements.txt --- requirements.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 1b54e4f..b6c06b5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,11 +3,13 @@ teachbooks # depends on jupyter-book jupyterbook-patches sphinx-image-inverter download_link_replacer -sphinx-exercise +git+https://github.com/TeachBooks/sphinx-exercise #waiting for merge of https://github.com/executablebooks/sphinx-exercise/pull/75, after, replace this line with `sphinx-exercise` teachbooks-sphinx-tippy sphinx-iframes sphinx-named-colors sphinx-dropdown-toggle +git+https://github.com/TeachBooks/sphinx-proof #waiting for merge of https://github.com/executablebooks/sphinx-proof/pull/146, after, replace this line with `sphinx-proof` +sphinx-code-examples # Now list the packages you want to download directly from GitHub git+https://github.com/TeachBooks/Sphinx-Thebe From 4d289a5006e45585801bd2b61a2006c9d0259aad Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 31 Jul 2025 08:27:25 +0200 Subject: [PATCH 041/109] Update requirements.txt --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index b6c06b5..195b3f9 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,7 +7,7 @@ git+https://github.com/TeachBooks/sphinx-exercise #waiting for merge of https:// teachbooks-sphinx-tippy sphinx-iframes sphinx-named-colors -sphinx-dropdown-toggle +git+https://github.com/TeachBooks/sphinx-togglebutton #waiting for merge of https://github.com/executablebooks/sphinx-togglebutton/pull/66, after, replace this line with `sphinx-dropdown-toggle` git+https://github.com/TeachBooks/sphinx-proof #waiting for merge of https://github.com/executablebooks/sphinx-proof/pull/146, after, replace this line with `sphinx-proof` sphinx-code-examples From 33ed511244fa4ce0edec9fa0b40fe6ee9dd1a025 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 31 Jul 2025 08:28:41 +0200 Subject: [PATCH 042/109] Update _config.yml --- book/_config.yml | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index d7032eb..aec63b7 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -40,14 +40,16 @@ sphinx: # Options passed on to the mtextInheritFont: true # To typeset text within math prettier } extra_extensions: # Gives you a starter package of extensions to use in your book - - jupyterbook_patches # Patches by TeachBooks https://github.com/TeachBooks/JupyterBook-Patches - - download_link_replacer # Allows you to replace and add downloadable files to a page header https://teachbooks.io/manual/external/Download-Link-Replacer/README.html - - sphinx_image_inverter # Inverts images for dark mode https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html - - sphinx_iframes # Eases the embedding of iframes https://teachbooks.io/manual/external/sphinx-iframes/README.html - - sphinx_exercise # Allows you to add exercise boxes to your book https://ebp-sphinx-exercise.readthedocs.io/en/latest/ - - teachbooks_sphinx_tippy # Enables hoover over tips https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html - - sphinx_named_colors # Allows you to use custom colors in your book https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html + - jupyterbook_patches # Various patches by TeachBooks: https://github.com/TeachBooks/JupyterBook-Patches + - download_link_replacer # Allows you to replace and add downloadable files to a page header: https://teachbooks.io/manual/external/Download-Link-Replacer/README.html + - sphinx_image_inverter # Inverts images for dark mode: https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html + - sphinx_iframes # Eases the embedding of iframes: https://teachbooks.io/manual/external/sphinx-iframes/README.html + - sphinx_exercise # Allows you to add exercise boxes to your book: https://ebp-sphinx-exercise.readthedocs.io/en/latest/ + - teachbooks_sphinx_tippy # Enables hoover over tips: https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html + - sphinx_named_colors # Allows you to use custom colors in your book: https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html - sphinx_dropdown_toggle # Adds a button to toggle all dropdowns with one click + - sphinx_proof # Allows you to add various mathy admonitions to your book: https://sphinx-proof.readthedocs.io/en/latest/ + - sphinx_code_examples # Allows you to include code blocks in examples: https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html bibtex_bibfiles: - references.bib # Required for references From d424efa5003634707917103568262539e5712ac6 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 31 Jul 2025 08:31:58 +0200 Subject: [PATCH 043/109] Update requirements.txt --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index 195b3f9..845ce49 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,6 +7,7 @@ git+https://github.com/TeachBooks/sphinx-exercise #waiting for merge of https:// teachbooks-sphinx-tippy sphinx-iframes sphinx-named-colors +sphinx_dropdown_toggle git+https://github.com/TeachBooks/sphinx-togglebutton #waiting for merge of https://github.com/executablebooks/sphinx-togglebutton/pull/66, after, replace this line with `sphinx-dropdown-toggle` git+https://github.com/TeachBooks/sphinx-proof #waiting for merge of https://github.com/executablebooks/sphinx-proof/pull/146, after, replace this line with `sphinx-proof` sphinx-code-examples From 499355a94f84490041ce3ec6eb387c34a86a0f8c Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 31 Jul 2025 10:29:39 +0200 Subject: [PATCH 044/109] Update _config.yml --- book/_config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_config.yml b/book/_config.yml index aec63b7..4fb8630 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -14,6 +14,7 @@ html: sphinx: # Options passed on to the underlying sphinx-parser config: + language: en # Defines language (English) of everything except the content itself. For Dutch: replace with `nl` html_js_files: - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js # Required for live code: https://teachbooks.io/manual/features/live_code.html thebe_config: From f5d17483f5c75f403e90e2894fa341b10adcc31c Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Mon, 11 Aug 2025 22:02:58 +0200 Subject: [PATCH 045/109] automatic indexing --- book/exercises/007.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/book/exercises/007.md b/book/exercises/007.md index d7b5256..d6c5d47 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -47,7 +47,16 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` This will appear as a hyperlink that takes the reader directly to the definition. -7. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. Check out the ever-growing list of TeachBooks extensions in the [TeachBooks manual](https://teachbooks.io/manual/features/overview.html)! + +7. The extension can also automatically index terms based on text formatting. In another `.md` file, try writing: + + ```md + This is a **strong term**, this is an *emphasised term*, and this is a `literal term`. + ``` + + When the book is built, these terms will be included in the generated index without needing to define them manually. You can view the index in the build output to confirm. + +8. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. Check out the ever-growing list of TeachBooks extensions in the [TeachBooks manual](https://teachbooks.io/manual/features/overview.html)! 8. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. From fe120cfe0a7a01ef401723acf3b9434931c73191 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 18 Aug 2025 10:50:10 +0200 Subject: [PATCH 046/109] close brackets --- book/exercises/007.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/exercises/007.md b/book/exercises/007.md index d6c5d47..d505f62 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -34,6 +34,7 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` ````{definition} Term :label: term-definition A word or phrase used to describe a concept or object. + ```` ````` This will render a labelled, indexed definition that you can refer to from other parts of your book. From 590cdc1474772b2c084fc4defc5085c562945a6d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 18 Aug 2025 10:51:47 +0200 Subject: [PATCH 047/109] Update summary.md --- book/exercises/summary.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/exercises/summary.md b/book/exercises/summary.md index a166a9d..d3cd5b0 100644 --- a/book/exercises/summary.md +++ b/book/exercises/summary.md @@ -15,12 +15,12 @@ Here is how these exercises relate to the workflow. | :---: | :---: | :---: | :---: | | 1 | Get and idea | 4 | Create an issue | | 2 | Create _your_ version of the book | 4 | Create a branch | -| 3 | Edit the book | 1, 2, 3, 6| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | -| 4 | Check changes online | 1, 2, 3, 6 | Workflows and Actions Summary | -| 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready| +| 3 | Edit the book | 1, 2, 3, 6, 8| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | +| 4 | Check changes online | 1, 2, 3, 6, 8 | Workflows and Actions Summary | +| 5 | Repeat edit and checking | 1, 2, 3, 4, 5, 8 | Keep on doing all the steps until it's ready| | 6 | Submit for review | 5, 7 | Open and merge a Pull Request, from a branch or forks | ## Keep practicing For additional practice, there are more exercises relating to the capacities of each user type. -Have a look in the [manual](https://teachbooks.io/manual/installation-and-setup/user_types.html) to see which user type you are! \ No newline at end of file +Have a look in the [manual](https://teachbooks.io/manual/installation-and-setup/user_types.html) to see which user type you are! From a9eb9c51c99417c49f4f76cbfa9bdd3ff7320165 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 27 Aug 2025 14:47:26 +0200 Subject: [PATCH 048/109] Add sphinx-accessibility to requirements.txt --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index 845ce49..91b3dc4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -11,6 +11,7 @@ sphinx_dropdown_toggle git+https://github.com/TeachBooks/sphinx-togglebutton #waiting for merge of https://github.com/executablebooks/sphinx-togglebutton/pull/66, after, replace this line with `sphinx-dropdown-toggle` git+https://github.com/TeachBooks/sphinx-proof #waiting for merge of https://github.com/executablebooks/sphinx-proof/pull/146, after, replace this line with `sphinx-proof` sphinx-code-examples +sphinx-accessibility # Now list the packages you want to download directly from GitHub git+https://github.com/TeachBooks/Sphinx-Thebe From 0026ee5d3ab92bb9211e692bd0cac42367ffb0bb Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 27 Aug 2025 14:49:12 +0200 Subject: [PATCH 049/109] Add sphinx_accessibility extension for better accessibility --- book/_config.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/_config.yml b/book/_config.yml index 4fb8630..770788e 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -51,6 +51,8 @@ sphinx: # Options passed on to the - sphinx_dropdown_toggle # Adds a button to toggle all dropdowns with one click - sphinx_proof # Allows you to add various mathy admonitions to your book: https://sphinx-proof.readthedocs.io/en/latest/ - sphinx_code_examples # Allows you to include code blocks in examples: https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html + - sphinx_accessibility # Allows dyslexic-friendly fonts and high contrast mode: https://teachbooks.io/manual/accessibility/_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.html + bibtex_bibfiles: - references.bib # Required for references From b73bc001ba1cffd6654d6674e7b9095861f8501e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 27 Aug 2025 14:53:39 +0200 Subject: [PATCH 050/109] Change dropdown hints to hint format --- book/syntax_exercises/013.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 62db026..39829c5 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -45,8 +45,8 @@ You can generate BibTeX entries using free tools like [ZoteroBib](https://zbib.o * `{cite:ps}` * `{cite:ts}` -```{dropdown} Hint: What to expect when you render these -:class: hint +```{hint} What to expect when you render these +:class: dropdown Here’s how the citation will appear for the example in the shared bibliography: @@ -107,8 +107,8 @@ sphinx: * `super` * `number` -```{dropdown} Hint: What each reference style will look like -:class: hint +```{hint} What each reference style will look like +:class: dropdown Heres's how each style will appear for the example in the shared bibliography: @@ -137,8 +137,8 @@ Feeling brave? You can also use APA references, although this is not a default o - `unsrt` - `unsrtalpha` -```{dropdown} Hint: What each bibliography style looks like -:class: hint +```{hint} What each bibliography style looks like +:class: dropdown Heres's how each style will appear for the example in the shared bibliography: From 4e1a0fe23e26027db373c5a3b0b57436aed17e39 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 27 Aug 2025 14:57:09 +0200 Subject: [PATCH 051/109] Clean up formatting in citation style hints Removed unnecessary line breaks in hints for citation styles. --- book/syntax_exercises/013.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 39829c5..1c501de 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -47,7 +47,6 @@ You can generate BibTeX entries using free tools like [ZoteroBib](https://zbib.o ```{hint} What to expect when you render these :class: dropdown - Here’s how the citation will appear for the example in the shared bibliography: - `{cite:p}` → **Parenthetical citation** @@ -109,7 +108,6 @@ sphinx: ```{hint} What each reference style will look like :class: dropdown - Heres's how each style will appear for the example in the shared bibliography: - `author_year` → Moore (2023) @@ -139,7 +137,6 @@ Feeling brave? You can also use APA references, although this is not a default o ```{hint} What each bibliography style looks like :class: dropdown - Heres's how each style will appear for the example in the shared bibliography: - `alpha` → References labelled as [Knu84], sorted by author/year From feb7dcaf6814d3d9fc0ef2d73f0801097d31dbc0 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 27 Aug 2025 15:00:33 +0200 Subject: [PATCH 052/109] Update hint block to admonition in syntax exercises --- book/syntax_exercises/013.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 1c501de..8fe41ba 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -45,8 +45,8 @@ You can generate BibTeX entries using free tools like [ZoteroBib](https://zbib.o * `{cite:ps}` * `{cite:ts}` -```{hint} What to expect when you render these -:class: dropdown +```{admonition} What to expect when you render these +:class: hint, dropdown Here’s how the citation will appear for the example in the shared bibliography: - `{cite:p}` → **Parenthetical citation** From bdb01f79aedbb6f79b83383fd2a108aaadf53df6 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 27 Aug 2025 15:04:22 +0200 Subject: [PATCH 053/109] Change hint to admonition for reference styles --- book/syntax_exercises/013.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 8fe41ba..4a1df77 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -106,8 +106,8 @@ sphinx: * `super` * `number` -```{hint} What each reference style will look like -:class: dropdown +```{admonition} What each reference style will look like +:class: hint, dropdown Heres's how each style will appear for the example in the shared bibliography: - `author_year` → Moore (2023) @@ -135,8 +135,8 @@ Feeling brave? You can also use APA references, although this is not a default o - `unsrt` - `unsrtalpha` -```{hint} What each bibliography style looks like -:class: dropdown +```{admonition} What each bibliography style looks like +:class: hint, dropdown Heres's how each style will appear for the example in the shared bibliography: - `alpha` → References labelled as [Knu84], sorted by author/year From 7709f0505794fec9b6a4ebc6b5c4e2aba6fb886a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 27 Aug 2025 16:05:10 +0200 Subject: [PATCH 054/109] Update requirements.txt --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index 91b3dc4..824a53d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -12,6 +12,7 @@ git+https://github.com/TeachBooks/sphinx-togglebutton #waiting for merge of http git+https://github.com/TeachBooks/sphinx-proof #waiting for merge of https://github.com/executablebooks/sphinx-proof/pull/146, after, replace this line with `sphinx-proof` sphinx-code-examples sphinx-accessibility +teachbooks-sphinx-tippy # Now list the packages you want to download directly from GitHub git+https://github.com/TeachBooks/Sphinx-Thebe From 093228089ffdf29b7b888989e5d8765b761a063b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 27 Aug 2025 16:09:09 +0200 Subject: [PATCH 055/109] Update _config.yml --- book/_config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_config.yml b/book/_config.yml index 770788e..dc76afc 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -52,6 +52,7 @@ sphinx: # Options passed on to the - sphinx_proof # Allows you to add various mathy admonitions to your book: https://sphinx-proof.readthedocs.io/en/latest/ - sphinx_code_examples # Allows you to include code blocks in examples: https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html - sphinx_accessibility # Allows dyslexic-friendly fonts and high contrast mode: https://teachbooks.io/manual/accessibility/_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.html + - teachbooks_sphinx_tippy # Adds rich hoover-over tips https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html bibtex_bibfiles: From d903ac497989c1dba50e26d0eb50e4a787142ed3 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 27 Aug 2025 17:41:49 +0200 Subject: [PATCH 056/109] Update _config.yml --- book/_config.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index dc76afc..a3a8f15 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -52,8 +52,6 @@ sphinx: # Options passed on to the - sphinx_proof # Allows you to add various mathy admonitions to your book: https://sphinx-proof.readthedocs.io/en/latest/ - sphinx_code_examples # Allows you to include code blocks in examples: https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html - sphinx_accessibility # Allows dyslexic-friendly fonts and high contrast mode: https://teachbooks.io/manual/accessibility/_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.html - - teachbooks_sphinx_tippy # Adds rich hoover-over tips https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html - bibtex_bibfiles: - references.bib # Required for references From 8fd477fc0f0686171ff9a7cf57c01c686660b5d7 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 27 Aug 2025 17:41:59 +0200 Subject: [PATCH 057/109] Remove teachbooks-sphinx-tippy from requirements Removed 'teachbooks-sphinx-tippy' from requirements. --- requirements.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 824a53d..91b3dc4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -12,7 +12,6 @@ git+https://github.com/TeachBooks/sphinx-togglebutton #waiting for merge of http git+https://github.com/TeachBooks/sphinx-proof #waiting for merge of https://github.com/executablebooks/sphinx-proof/pull/146, after, replace this line with `sphinx-proof` sphinx-code-examples sphinx-accessibility -teachbooks-sphinx-tippy # Now list the packages you want to download directly from GitHub git+https://github.com/TeachBooks/Sphinx-Thebe From 62b30a560b64901259b953e398e22b53d85c56b0 Mon Sep 17 00:00:00 2001 From: Dennis den Ouden-van der Horst Date: Thu, 28 Aug 2025 11:51:18 +0200 Subject: [PATCH 058/109] Replace individual Sphinx extensions with favourites package Consolidated multiple Sphinx extension dependencies into the 'teachbooks_favourites' package in both _config.yml and requirements.txt. This simplifies configuration and dependency management by using a single package that includes the preferred extensions. --- book/_config.yml | 14 ++------------ requirements.txt | 15 +++------------ 2 files changed, 5 insertions(+), 24 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index a3a8f15..00509ad 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -40,18 +40,8 @@ sphinx: # Options passed on to the chtml: { mtextInheritFont: true # To typeset text within math prettier } - extra_extensions: # Gives you a starter package of extensions to use in your book - - jupyterbook_patches # Various patches by TeachBooks: https://github.com/TeachBooks/JupyterBook-Patches - - download_link_replacer # Allows you to replace and add downloadable files to a page header: https://teachbooks.io/manual/external/Download-Link-Replacer/README.html - - sphinx_image_inverter # Inverts images for dark mode: https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html - - sphinx_iframes # Eases the embedding of iframes: https://teachbooks.io/manual/external/sphinx-iframes/README.html - - sphinx_exercise # Allows you to add exercise boxes to your book: https://ebp-sphinx-exercise.readthedocs.io/en/latest/ - - teachbooks_sphinx_tippy # Enables hoover over tips: https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html - - sphinx_named_colors # Allows you to use custom colors in your book: https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html - - sphinx_dropdown_toggle # Adds a button to toggle all dropdowns with one click - - sphinx_proof # Allows you to add various mathy admonitions to your book: https://sphinx-proof.readthedocs.io/en/latest/ - - sphinx_code_examples # Allows you to include code blocks in examples: https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html - - sphinx_accessibility # Allows dyslexic-friendly fonts and high contrast mode: https://teachbooks.io/manual/accessibility/_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.html + extra_extensions: + - teachbooks_favourites # Gives you a starter package of extensions to use in your book bibtex_bibfiles: - references.bib # Required for references diff --git a/requirements.txt b/requirements.txt index 91b3dc4..faa7636 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,17 +1,8 @@ # first list the packages you wish to download from PyPI teachbooks # depends on jupyter-book -jupyterbook-patches -sphinx-image-inverter -download_link_replacer -git+https://github.com/TeachBooks/sphinx-exercise #waiting for merge of https://github.com/executablebooks/sphinx-exercise/pull/75, after, replace this line with `sphinx-exercise` -teachbooks-sphinx-tippy -sphinx-iframes -sphinx-named-colors -sphinx_dropdown_toggle -git+https://github.com/TeachBooks/sphinx-togglebutton #waiting for merge of https://github.com/executablebooks/sphinx-togglebutton/pull/66, after, replace this line with `sphinx-dropdown-toggle` -git+https://github.com/TeachBooks/sphinx-proof #waiting for merge of https://github.com/executablebooks/sphinx-proof/pull/146, after, replace this line with `sphinx-proof` -sphinx-code-examples -sphinx-accessibility + +# Our favourite Sphinx extensions in one line +git+https://github.com/TeachBooks/TeachBooks-Favourites # Now list the packages you want to download directly from GitHub git+https://github.com/TeachBooks/Sphinx-Thebe From dc45f7a1f40df0b3f89098c97330b8b6e595ea9f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 28 Aug 2025 14:16:06 +0200 Subject: [PATCH 059/109] Clarify teachbooks_favourites extension usage Updated comment for teachbooks_favourites extension to clarify usage. --- book/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_config.yml b/book/_config.yml index 00509ad..2805148 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -41,7 +41,7 @@ sphinx: # Options passed on to the mtextInheritFont: true # To typeset text within math prettier } extra_extensions: - - teachbooks_favourites # Gives you a starter package of extensions to use in your book + - teachbooks_favourites # Gives you a starter package of extensions to use in your book, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) bibtex_bibfiles: - references.bib # Required for references From 08f361761423c026125ef97ced0da538f4c65616 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 28 Aug 2025 14:16:21 +0200 Subject: [PATCH 060/109] Clarify Sphinx extensions comment in requirements.txt Updated comment for Sphinx extensions and clarified usage. --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index faa7636..6f82337 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,7 +1,7 @@ # first list the packages you wish to download from PyPI teachbooks # depends on jupyter-book -# Our favourite Sphinx extensions in one line +# Our favourite Sphinx extensions in one line, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) git+https://github.com/TeachBooks/TeachBooks-Favourites # Now list the packages you want to download directly from GitHub From 7c0e44ac7334f5be16b4ab72150c35769be3122a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 28 Aug 2025 14:56:26 +0200 Subject: [PATCH 061/109] Update GitHub dependencies in requirements.txt --- requirements.txt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/requirements.txt b/requirements.txt index 6f82337..e881ebd 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,7 +2,4 @@ teachbooks # depends on jupyter-book # Our favourite Sphinx extensions in one line, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) -git+https://github.com/TeachBooks/TeachBooks-Favourites - -# Now list the packages you want to download directly from GitHub -git+https://github.com/TeachBooks/Sphinx-Thebe +git+https://github.com/TeachBooks/TeachBooks-Favourites@add-sphinx-thebe From 0384138d9db33991cd447ec56444426ebb0d8f60 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 28 Aug 2025 14:59:28 +0200 Subject: [PATCH 062/109] Update TeachBooks Favourites repository URL --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index e881ebd..0479af9 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,4 @@ teachbooks # depends on jupyter-book # Our favourite Sphinx extensions in one line, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) -git+https://github.com/TeachBooks/TeachBooks-Favourites@add-sphinx-thebe +git+https://github.com/TeachBooks/TeachBooks-Favourites From 0a2f1514896696cb811c888bcd2c658ccdcfabd9 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sun, 7 Sep 2025 13:29:02 +0200 Subject: [PATCH 063/109] live code exercise 1 --- book/_toc.yml | 3 + book/exercises/live_exercises/014.md | 86 ++++++++++++++++++++++++++++ book/live_exercises.md | 5 ++ book/syntax_exercises/007.md | 2 +- book/syntax_exercises/008.md | 2 +- book/syntax_exercises/009.md | 2 +- book/syntax_exercises/010.md | 2 +- book/syntax_exercises/011.md | 2 +- book/syntax_exercises/012.md | 2 +- book/syntax_exercises/013.md | 2 +- 10 files changed, 101 insertions(+), 7 deletions(-) create mode 100644 book/exercises/live_exercises/014.md create mode 100644 book/live_exercises.md diff --git a/book/_toc.yml b/book/_toc.yml index e93a13f..a4127e9 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -27,6 +27,9 @@ parts: - file: syntax_exercises/011.md - file: syntax_exercises/012.md - file: syntax_exercises/013.md + - file: live_exercises.md + sections: + - file: live_exercises/014.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/live_exercises/014.md b/book/exercises/live_exercises/014.md new file mode 100644 index 0000000..8f75b2a --- /dev/null +++ b/book/exercises/live_exercises/014.md @@ -0,0 +1,86 @@ +# Exercise 16: Custom cell tags + +With the extended functionality of live code, additional cell tags have been developed that can be added to Python code cells in any `.ipynb` file. These tags extend the [existing Jupyter Book tags](https://jupyterbook.org/en/stable/content/metadata.html) and allow you to control how cells behave when live execution is enabled. + +::::::{topic} Exercise objective +Can you apply custom cell tags to control the execution and visibility of code cells? +:::::: + +## Available custom tags + +- `disable-execution-cell` disables the ability to execute the cell when live code is activated. This is useful if your notebook includes interactivity for only part of the cells. +- `disable-execution-page` disables the ability to execute the entire page. This can be helpful if Python code is used to build a page but is not meant to be run by readers. +- `auto-execute-page` automatically starts live coding when the page is opened, useful if you are using widgets. +- `thebe-init` runs this cell automatically as soon as live coding starts. +- `thebe-remove-input-init` is similar to `thebe-init` but hides the input from students while still executing it. (The regular `remove-input` tag will not work here, since it deletes the entire cell.) + +```{tip} +Tags are case-sensitive. Use lowercase and match them exactly as shown above. +```` + + +## Creating a notebook + +1. In your repository, create a new notebook file in your book directory, e.g. `book/live_code_tags.ipynb`. +2. Add a new code cell with something simple inside, for example: + +```python +print("Hello from live code!") +``` + +3. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +4. Add a commit message. + +5. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). + +6. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + +## `disable-execution-cell` + +7. Now let's go back to your notebook. Open the cell metadata (in JupyterLab or Jupyter Notebook: `View → Cell Toolbar → Tags`). +8. Add the tag `disable-execution-cell` to your code cell, and commit and rebuild your book. +9. Visit the page — notice that this particular cell can no longer be run when live code is activated. + +## `disable-execution-page` + +10. Add another code cell to your file, for example: + +```python +print("Goodbye from live code!") +``` +11. Add the tag `disable-execution-page` to any of the live cell codes in your file, and commit and rebuild your book. +12. Visit the page — none of the cells should be executable now. + +```{note} +Remove this tag again before continuing, otherwise the next tags won’t have any effect. +``` + +## `auto-execute-page` + +13. Add the tag `auto-execute-page` to any cell and rebuild your book. +14. Visit the page — live code should automatically start running without clicking the “launch” button. + +## `thebe-init` + +15. Add the tag `thebe-init` to any cell and rebuild your book. +16. Visit the page — as soon as live code starts, this cell will run by itself. + +## `thebe-remove-input-init` + +17. Replace the previous tag with `thebe-remove-input-init`, and rebuild your book. +18. Visit the page — you should only see the **output** of the cell, not the code, but the cell is still executed automatically when live code starts. + + + + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you understand the following: +- How do you add tags to a cell in an `.ipynb` file? +- Which tag disables execution for a single cell? For the whole page? +- Which tag makes a page auto-start live code when opened? +- What is the difference between `thebe-init` and `thebe-remove-input-init`? +``` + diff --git a/book/live_exercises.md b/book/live_exercises.md new file mode 100644 index 0000000..7eee81a --- /dev/null +++ b/book/live_exercises.md @@ -0,0 +1,5 @@ +# Live code exercises + +The previous exercises introduced you to the basics of writing content for your TeachBook, as well as getting started with the syntax used. Now let’s explore how you can make your pages more interactive by adding live, executable code cells. + +With live code enabled, readers can run snippets directly in the browser, experiment with examples, and complete exercises in real time. This section will guide you through some of the main features and options available. \ No newline at end of file diff --git a/book/syntax_exercises/007.md b/book/syntax_exercises/007.md index bb12b9e..7b28f02 100644 --- a/book/syntax_exercises/007.md +++ b/book/syntax_exercises/007.md @@ -1,4 +1,4 @@ -# Exercise 7: File structure by titles +# Exercise 9: File structure by titles In this exercise you will learn how to structure your chapters. diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index 2ca453f..fbb84b5 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -1,4 +1,4 @@ -# Exercise 8: Add visual media +# Exercise 10: Add visual media To help you illustrate your content, it can be useful to add some type of visual media such as figures, gifs or videos. If you want to add a figure/gif to your book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale). diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 9598393..9259eb2 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -1,4 +1,4 @@ -# Exercise 9: Use equations +# Exercise 11: Use equations In this exercise, you will learn how to write and format mathematical equations in your TeachBook, both inline and as standalone blocks. diff --git a/book/syntax_exercises/010.md b/book/syntax_exercises/010.md index ccb14a0..9fe7377 100644 --- a/book/syntax_exercises/010.md +++ b/book/syntax_exercises/010.md @@ -1,4 +1,4 @@ -# Exercise 10: Create tables +# Exercise 12: Create tables In this exercise, we will explore how to create and format tables in your TeachBook using Markdown and reStructuredText. diff --git a/book/syntax_exercises/011.md b/book/syntax_exercises/011.md index a40da80..868e49b 100644 --- a/book/syntax_exercises/011.md +++ b/book/syntax_exercises/011.md @@ -1,4 +1,4 @@ -# Exercise 11: Cross-referencing content +# Exercise 13: Cross-referencing content In this exercise, you will learn how to create references to other parts of your book, such as chapters, sections, equations, tables and figures, as well as links. diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md index 6f80704..77e023f 100644 --- a/book/syntax_exercises/012.md +++ b/book/syntax_exercises/012.md @@ -1,4 +1,4 @@ -# Exercise 12: Use admonitions +# Exercise 14: Use admonitions In this exercise, you will learn how to use admonitions to enhance the readability and structure of your TeachBook content. Admonitions are special highlighted blocks that are useful for tips, warnings, notes, and more. diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index 4a1df77..e8f87c7 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -1,5 +1,5 @@ -# Exercise 13: Adding a Bibliography +# Exercise 15: Adding a Bibliography In this exercise, you will learn how to cite sources using the shared bibliography provided in this template, and how to control the citation style and reference formatting using `{cite}` roles and the `{bibliography}` directive. From 872e64d124e2dfd1de522f508222d63fa10dfb69 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sun, 7 Sep 2025 13:32:47 +0200 Subject: [PATCH 064/109] updated file --- book/{exercises => }/live_exercises/014.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename book/{exercises => }/live_exercises/014.md (100%) diff --git a/book/exercises/live_exercises/014.md b/book/live_exercises/014.md similarity index 100% rename from book/exercises/live_exercises/014.md rename to book/live_exercises/014.md From 8d8b94759e99c17ecf31945ab4a8c8948da58a1a Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 13 Sep 2025 18:36:11 +0200 Subject: [PATCH 065/109] Update 014.md --- book/live_exercises/014.md | 214 +++++++++++++++++++++++++++++++------ 1 file changed, 179 insertions(+), 35 deletions(-) diff --git a/book/live_exercises/014.md b/book/live_exercises/014.md index 8f75b2a..b537a84 100644 --- a/book/live_exercises/014.md +++ b/book/live_exercises/014.md @@ -1,6 +1,6 @@ # Exercise 16: Custom cell tags -With the extended functionality of live code, additional cell tags have been developed that can be added to Python code cells in any `.ipynb` file. These tags extend the [existing Jupyter Book tags](https://jupyterbook.org/en/stable/content/metadata.html) and allow you to control how cells behave when live execution is enabled. +With the extended functionality of live code, additional cell tags have been developed that can be added to Python code cells in your book. These tags extend the [existing Jupyter Book tags](https://jupyterbook.org/en/stable/content/metadata.html) and allow you to control how cells behave when live execution is enabled. ::::::{topic} Exercise objective Can you apply custom cell tags to control the execution and visibility of code cells? @@ -18,69 +18,213 @@ Can you apply custom cell tags to control the execution and visibility of code c Tags are case-sensitive. Use lowercase and match them exactly as shown above. ```` - ## Creating a notebook +There are two ways you can try this exercise, depending on whether you have an IDE installed. + +### Option 1: Using JupyterLab or VS Code (if installed) + 1. In your repository, create a new notebook file in your book directory, e.g. `book/live_code_tags.ipynb`. -2. Add a new code cell with something simple inside, for example: +2. To add a new code cell, use `python` and enter a simple code, for example: +````md ```python -print("Hello from live code!") +print("Hello world!") +``` +````md + +3. With this setup, tags can be added by opening the cell metadata (in JupyterLab or Jupyter Notebook: `View → Cell Toolbar → Tags`). + + +### Option 2: Using Jupytext in Markdown + +4. If you don’t have JupyterLab or VS Code installed, you can still add code by writing a Markdown file with a Jupytext header. At the very top of your file (e.g. `book/live_code_tags.md`), add: + +```yaml +--- +jupytext: + text_representation: + extension: .md + format_name: myst + format_version: 0.13 + jupytext_version: 1.17.3 +kernelspec: + display_name: base + language: python + name: python3 +--- ``` -3. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +5. Now you can insert executable code cells with tags like this: -4. Add a commit message. - -5. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). - -6. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. - -## `disable-execution-cell` - -7. Now let's go back to your notebook. Open the cell metadata (in JupyterLab or Jupyter Notebook: `View → Cell Toolbar → Tags`). -8. Add the tag `disable-execution-cell` to your code cell, and commit and rebuild your book. -9. Visit the page — notice that this particular cell can no longer be run when live code is activated. - -## `disable-execution-page` - -10. Add another code cell to your file, for example: - -```python -print("Goodbye from live code!") +````md +```{code-cell} ipython3 +print("Hello world!") ``` -11. Add the tag `disable-execution-page` to any of the live cell codes in your file, and commit and rebuild your book. -12. Visit the page — none of the cells should be executable now. +```` + +6. With this setup, tags can be added directly into the code cell using `:tags:`. + + + +## Trying the custom tags + +Now that you know how to create executable code cells, let’s explore the different custom tags available and see examples of how each one can control the behavior of your code when live execution is enabled. + + +### `disable-execution-cell` + +7. This tag is useful when you want a particular code cell to display content without being executed by readers. For example, let’s set up a new cell that prints the current date and time only once: + +**Option 1: Using JupyterLab or VS Code** + +````md +```python +import datetime + +# This prints the current date and time once +current_time = datetime.datetime.now() +print("This notebook was last updated at:", current_time) +``` +````md + +*Remember to add the tag `disable-execution-cell` locally via the cell metadata (`View → Cell Toolbar → Tags`).* + + +**Option 2: Using Jupytext in Markdown** + +````md +```{code-cell} ipython3 +:tags: ["disable-execution-cell"] + +import datetime + +# This prints the current date and time once +current_time = datetime.datetime.now() +print("This notebook was last updated at:", current_time) +``` +````md + +8. Commit and rebuild your book and visit the page — notice that this particular cell can no longer be run when live code is activated. + +### `disable-execution-page` + +9. This tag is useful when you want all code cells on a page to be non-executable. This is handy if the code is used to build the page or provide context, but you don’t want readers to run it themselves. Add the tag `disable-execution-page` to any of the code cells in your file. + +10. Commit and rebuild your book and visit the page — none of the cells should be executable now. ```{note} Remove this tag again before continuing, otherwise the next tags won’t have any effect. ``` -## `auto-execute-page` +### `auto-execute-page` -13. Add the tag `auto-execute-page` to any cell and rebuild your book. -14. Visit the page — live code should automatically start running without clicking the “launch” button. +11. This tag is useful when you want live code to start running automatically as soon as the page is opened. This is particularly helpful when using visualizations or interactive widgets that should initialize immediately. For example, let's set up a plot: -## `thebe-init` +**Option 1: Using JupyterLab or VS Code** -15. Add the tag `thebe-init` to any cell and rebuild your book. -16. Visit the page — as soon as live code starts, this cell will run by itself. +````md +```python +import matplotlib.pyplot as plt +import numpy as np -## `thebe-remove-input-init` +x = np.linspace(0, 10, 100) +y = np.sin(x) -17. Replace the previous tag with `thebe-remove-input-init`, and rebuild your book. -18. Visit the page — you should only see the **output** of the cell, not the code, but the cell is still executed automatically when live code starts. +plt.plot(x, y) +plt.title("Sine wave") +plt.show() +``` +````md + +*Remember to add the tag `auto-execute-page` to one of the cells via the cell metadata (`View → Cell Toolbar → Tags`).* +**Option 2: Using Jupytext in Markdown** + +````md +```{code-cell} ipython3 +:tags: ["auto-execute-page"] + +import matplotlib.pyplot as plt +import numpy as np + +x = np.linspace(0, 10, 100) +y = np.sin(x) + +plt.plot(x, y) +plt.title("Sine wave") +plt.show() +``` +````md + +12. Commit and rebuild your book and visit the page — the plot should appear automatically without needing to click the “launch” button. + + + +### `thebe-init` + + +13. The `thebe-init` tag is useful when you want a specific cell to run automatically as soon as live coding starts. This is especially helpful for initializing variables that other cells depend on. For example, let's initialize a dataset of student names and their scores: + +**Option 1: Using JupyterLab or VS Code** + +````md +```python +# Initialize dataset +students = ["Alice", "Bob", "Charlie", "Diana"] +scores = [85, 92, 78, 90] + +print("Initialized dataset with students and scores") +``` +````md + +*Remember to add the tag `thebe-init` locally via the cell metadata (`View → Cell Toolbar → Tags`).* + + +**Option 2: Using Jupytext in Markdown** + +````md +```{code-cell} ipython3 +:tags: ["thebe-init"] + +# Initialize dataset +students = ["Alice", "Bob", "Charlie", "Diana"] +scores = [85, 92, 78, 90] + +print("Initialized dataset with students and scores") +``` +````md + +14. Commit and rebuild your book and visit the page — as soon as live code starts, this cell will run by itself. + + +### `thebe-remove-input-init` + +15. This tag works similarly to `thebe-init`, but the input (code) is hidden from students, so they only see the output. This is useful when you want to initialize variables or datasets without showing implementation details. To try this, simply replace the previous tag `thebe-init` with `thebe-remove-input-init` in the same cell from the previous example. + +16. Commit and rebuild your book and visit the page — the cell will **run automatically**, but students will only see the output, not the code. + + +17. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +18. Add a commit message. + +19. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). + +20. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding :class: note Before moving on, make sure you understand the following: -- How do you add tags to a cell in an `.ipynb` file? +- How do you add tags to a code cell in your book? - Which tag disables execution for a single cell? For the whole page? - Which tag makes a page auto-start live code when opened? - What is the difference between `thebe-init` and `thebe-remove-input-init`? ``` + + + From 802fc2784326b5b1f8cdd87ae3f93969d135f36b Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 13 Sep 2025 18:53:50 +0200 Subject: [PATCH 066/109] fixed md --- book/live_exercises/014.md | 50 +++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/book/live_exercises/014.md b/book/live_exercises/014.md index b537a84..d788876 100644 --- a/book/live_exercises/014.md +++ b/book/live_exercises/014.md @@ -31,14 +31,14 @@ There are two ways you can try this exercise, depending on whether you have an I ```python print("Hello world!") ``` -````md +```` -3. With this setup, tags can be added by opening the cell metadata (in JupyterLab or Jupyter Notebook: `View → Cell Toolbar → Tags`). +With this setup, tags can be added by opening the cell metadata (in JupyterLab or Jupyter Notebook: `View → Cell Toolbar → Tags`). ### Option 2: Using Jupytext in Markdown -4. If you don’t have JupyterLab or VS Code installed, you can still add code by writing a Markdown file with a Jupytext header. At the very top of your file (e.g. `book/live_code_tags.md`), add: +3. If you don’t have JupyterLab or VS Code installed, you can still add code by writing a Markdown file with a Jupytext header. At the very top of your file (e.g. `book/live_code_tags.md`), add: ```yaml --- @@ -55,7 +55,7 @@ kernelspec: --- ``` -5. Now you can insert executable code cells with tags like this: +4. Now you can insert executable code cells with tags like this: ````md ```{code-cell} ipython3 @@ -63,7 +63,7 @@ print("Hello world!") ``` ```` -6. With this setup, tags can be added directly into the code cell using `:tags:`. +With this setup, tags can be added directly into the code cell using `:tags:`. @@ -74,7 +74,7 @@ Now that you know how to create executable code cells, let’s explore the diffe ### `disable-execution-cell` -7. This tag is useful when you want a particular code cell to display content without being executed by readers. For example, let’s set up a new cell that prints the current date and time only once: +5. This tag is useful when you want a particular code cell to display content without being executed by readers. For example, let’s set up a new cell that prints the current date and time only once: **Option 1: Using JupyterLab or VS Code** @@ -86,7 +86,7 @@ import datetime current_time = datetime.datetime.now() print("This notebook was last updated at:", current_time) ``` -````md +```` *Remember to add the tag `disable-execution-cell` locally via the cell metadata (`View → Cell Toolbar → Tags`).* @@ -103,15 +103,15 @@ import datetime current_time = datetime.datetime.now() print("This notebook was last updated at:", current_time) ``` -````md +```` -8. Commit and rebuild your book and visit the page — notice that this particular cell can no longer be run when live code is activated. +6. Commit and rebuild your book and visit the page — notice that this particular cell can no longer be run when live code is activated. ### `disable-execution-page` -9. This tag is useful when you want all code cells on a page to be non-executable. This is handy if the code is used to build the page or provide context, but you don’t want readers to run it themselves. Add the tag `disable-execution-page` to any of the code cells in your file. +7. This tag is useful when you want all code cells on a page to be non-executable. This is handy if the code is used to build the page or provide context, but you don’t want readers to run it themselves. Add the tag `disable-execution-page` to any of the code cells in your file. -10. Commit and rebuild your book and visit the page — none of the cells should be executable now. +8. Commit and rebuild your book and visit the page — none of the cells should be executable now. ```{note} Remove this tag again before continuing, otherwise the next tags won’t have any effect. @@ -119,7 +119,7 @@ Remove this tag again before continuing, otherwise the next tags won’t have an ### `auto-execute-page` -11. This tag is useful when you want live code to start running automatically as soon as the page is opened. This is particularly helpful when using visualizations or interactive widgets that should initialize immediately. For example, let's set up a plot: +9. This tag is useful when you want live code to start running automatically as soon as the page is opened. This is particularly helpful when using visualizations or interactive widgets that should initialize immediately. For example, let's set up a plot: **Option 1: Using JupyterLab or VS Code** @@ -135,7 +135,7 @@ plt.plot(x, y) plt.title("Sine wave") plt.show() ``` -````md +```` *Remember to add the tag `auto-execute-page` to one of the cells via the cell metadata (`View → Cell Toolbar → Tags`).* @@ -156,16 +156,16 @@ plt.plot(x, y) plt.title("Sine wave") plt.show() ``` -````md +```` -12. Commit and rebuild your book and visit the page — the plot should appear automatically without needing to click the “launch” button. +10. Commit and rebuild your book and visit the page — the plot should appear automatically without needing to click the “launch” button. ### `thebe-init` -13. The `thebe-init` tag is useful when you want a specific cell to run automatically as soon as live coding starts. This is especially helpful for initializing variables that other cells depend on. For example, let's initialize a dataset of student names and their scores: +11. The `thebe-init` tag is useful when you want a specific cell to run automatically as soon as live coding starts. This is especially helpful for initializing variables that other cells depend on. For example, let's initialize a dataset of student names and their scores: **Option 1: Using JupyterLab or VS Code** @@ -177,7 +177,7 @@ scores = [85, 92, 78, 90] print("Initialized dataset with students and scores") ``` -````md +```` *Remember to add the tag `thebe-init` locally via the cell metadata (`View → Cell Toolbar → Tags`).* @@ -194,25 +194,25 @@ scores = [85, 92, 78, 90] print("Initialized dataset with students and scores") ``` -````md +```` -14. Commit and rebuild your book and visit the page — as soon as live code starts, this cell will run by itself. +12. Commit and rebuild your book and visit the page — as soon as live code starts, this cell will run by itself. ### `thebe-remove-input-init` -15. This tag works similarly to `thebe-init`, but the input (code) is hidden from students, so they only see the output. This is useful when you want to initialize variables or datasets without showing implementation details. To try this, simply replace the previous tag `thebe-init` with `thebe-remove-input-init` in the same cell from the previous example. +13. This tag works similarly to `thebe-init`, but the input (code) is hidden from students, so they only see the output. This is useful when you want to initialize variables or datasets without showing implementation details. To try this, simply replace the previous tag `thebe-init` with `thebe-remove-input-init` in the same cell from the previous example. -16. Commit and rebuild your book and visit the page — the cell will **run automatically**, but students will only see the output, not the code. +14. Commit and rebuild your book and visit the page — the cell will **run automatically**, but students will only see the output, not the code. -17. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +15. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -18. Add a commit message. +16. Add a commit message. -19. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +17. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). -20. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +18. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding From 4c2bc95f750f785f98c056e831d7d7aa5941cc76 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 13 Sep 2025 18:57:22 +0200 Subject: [PATCH 067/109] final update --- book/live_exercises/014.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/live_exercises/014.md b/book/live_exercises/014.md index d788876..fc336d9 100644 --- a/book/live_exercises/014.md +++ b/book/live_exercises/014.md @@ -203,7 +203,7 @@ print("Initialized dataset with students and scores") 13. This tag works similarly to `thebe-init`, but the input (code) is hidden from students, so they only see the output. This is useful when you want to initialize variables or datasets without showing implementation details. To try this, simply replace the previous tag `thebe-init` with `thebe-remove-input-init` in the same cell from the previous example. -14. Commit and rebuild your book and visit the page — the cell will **run automatically**, but students will only see the output, not the code. +14. Commit and rebuild your book and visit the page — the cell will run automatically, but students will only see the output, not the code. 15. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. From 0417de8ebc6efa0af72ba44ee73139d868ee1862 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 08:19:00 +0200 Subject: [PATCH 068/109] Update _config.yml with TeachBooks attribution settings --- book/_config.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/book/_config.yml b/book/_config.yml index 2805148..584ff66 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -40,8 +40,13 @@ sphinx: # Options passed on to the chtml: { mtextInheritFont: true # To typeset text within math prettier } + named_colors_custom_colors: {'attributiongrey':[150,150,150]} # Defines grey colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) extra_extensions: - teachbooks_favourites # Gives you a starter package of extensions to use in your book, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) +teachbooks: + attribution_location: top # Default value, sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) + attribution_color: attributiongrey # Sets grey colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) + bibtex_bibfiles: - references.bib # Required for references From 30909e1406b49b9c44bfad8e6eff7dfe24962004 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 08:20:50 +0200 Subject: [PATCH 069/109] Create attribution.css for TeachBooks package --- book/_static/attribution.css | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 book/_static/attribution.css diff --git a/book/_static/attribution.css b/book/_static/attribution.css new file mode 100644 index 0000000..4c71166 --- /dev/null +++ b/book/_static/attribution.css @@ -0,0 +1,4 @@ +/* Set attribution admonition symbol, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) */ +div.attribution > .admonition-title::after { + content: "\f10d"; +} From 776d252faacf6788b78cedba637d48dc1df42e42 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 08:56:38 +0200 Subject: [PATCH 070/109] Modify _config.yml for Sphinx settings Updated configuration options for live code and added new settings for Sphinx extensions. --- book/_config.yml | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index 584ff66..fd475ba 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -16,10 +16,10 @@ sphinx: # Options passed on to the config: language: en # Defines language (English) of everything except the content itself. For Dutch: replace with `nl` html_js_files: - - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js # Required for live code: https://teachbooks.io/manual/features/live_code.html + - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js # Required for live code, part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html) thebe_config: - use_thebe_lite: true # Required for live code: https://teachbooks.io/manual/features/live_code.html - exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] #exclude files which should not be accessible for live code: https://teachbooks.io/manual/features/live_code.html + use_thebe_lite: true # Required for live code, part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html) + exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] #exclude files which should not be accessible for live code, configuration part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html) html_theme_options: logo: text: Template # Replace this with your own book title @@ -32,7 +32,7 @@ sphinx: # Options passed on to the use_repository_button: true # Replace with false if you don't want the repository button (i.e. if you have a private repo) use_issues_button : true # Replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo) launch_buttons: - thebe: true # Required for live code: https://teachbooks.io/manual/features/live_code.html + thebe: true # Required for live code, part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html) html_show_copyright: false # As the copyright is included in the author field html_last_updated_fmt: '%B %-d, %Y' # Adds the date of the last update to the footer html_static_path: ["figures"] # Add folder that contain files that need to be included, such as the location of the logo(s) @@ -40,13 +40,36 @@ sphinx: # Options passed on to the chtml: { mtextInheritFont: true # To typeset text within math prettier } - named_colors_custom_colors: {'attributiongrey':[150,150,150]} # Defines grey colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) + patch_config: + disabled-patches: [] # Default value (line can be removed), disables specific patches, configuration part of JupyterBook-Patches (https://teachbooks.io/manual/external/JupyterBook-Patches/README.html) + inverter_all: true # Default value (line can be removed), inverts all figures, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html) + inverter_saturation: 1.5 # Default value (line can be removed), sets saturation of figures in dark mode to 1.5, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html) + iframe_blend: true # Default value (line can be removed), blends all iframes with the background and in dark-mode also inverted., configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html) + iframe_saturation: 1.5 # Default value (line can be removed), sets saturation of iframes in dark mode to 1.5, configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html) + iframe_h5p_autoresize: true # Default value (line can be removed), automagically resized all h5p elements to fit the element in which the iframe is loadeds, configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html) + iframe_background: "#ffffff" # Default value (line can be removed), sets the standard background color of non-blended iframes to white, configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html) + iframe_width: calc(100% - 2.8rem) # Default value (line can be removed), sets the standard width of the iframe within the parent element, configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html) + iframe_aspectratio: auto 2 / 1 # Default value (line can be removed), sets the standard aspect ration of the iframe within the parent element, configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html) + hide_solutions: false # Default value (line can be removed), does not hide all solutions from exercises, configuration part of Sphinx-Exercise (https://ebp-sphinx-exercise.readthedocs.io/en/latest/syntax.html) + named_colors_include_CSS: true # Default value (line can be removed), includes all CSS colours, configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html) + named_colors_dark_and_light: true # Default value (line can be removed), creates dark mode colours for CSS and custom named colours, configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html) + named_colors_saturation: 1.5 # Default value (line can be removed), sets saturation of CSS and custom named colours in dark mode to 1.5, configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html) + named_colors_custom_colors: None # Default value (line can be removed), defines no custom named colours (include no colour for attribution admonition of external pages), configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html) + proof_minimal_theme: false # Default value (line can be removed), uses default color scheme for admonitions part of sphinx-proof, configuration part of Sphinx-Proof (https://sphinx-proof.readthedocs.io/en/latest/options.html) + sphinx_codex_name: "" # Default value (line can be removed), uses default 'Code example' as title for codex directives, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) + sphinx_codex_style_from_proof: true # Default value (line can be removed), the CSS color style of the codex directive will be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) + sphinx_codex_icon_from_proof: false # Default value (line can be removed), the icon of the codex directive will not be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) + sphinx_codex_merge_with_proof: false # Default value (line can be removed), the codex directive will not be merged with the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) + sphinx_togglebutton_selector: ".toggle, .admonition.dropdown" # Default value (line can be removed), configures the CSS selector used to insert toggle buttons, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html + togglebutton_hint: "Click to show" # Default value (line can be removed), defines hint when toggle is closed, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html + togglebutton_hint_hide: "Click to hide" # Default value (line can be removed), defines hint when toggle is opened, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html + togglebutton_open_on_print: true # Default value (line can be removed), opens all toggle-able content when you print, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html extra_extensions: - teachbooks_favourites # Gives you a starter package of extensions to use in your book, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) teachbooks: - attribution_location: top # Default value, sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) - attribution_color: attributiongrey # Sets grey colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) + attribution_location: top # Default value (line can be removed), sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) + attribution_color: None # Default value (line can be removed), uses blue colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) bibtex_bibfiles: - references.bib # Required for references From 096cd840ff0212073de5d5177d174c86c217a246 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 08:58:05 +0200 Subject: [PATCH 071/109] Delete book/_static directory --- book/_static/attribution.css | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 book/_static/attribution.css diff --git a/book/_static/attribution.css b/book/_static/attribution.css deleted file mode 100644 index 4c71166..0000000 --- a/book/_static/attribution.css +++ /dev/null @@ -1,4 +0,0 @@ -/* Set attribution admonition symbol, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) */ -div.attribution > .admonition-title::after { - content: "\f10d"; -} From dc8021453ec6686def617f02ff4d3e0a9ecbcd7e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 09:05:11 +0200 Subject: [PATCH 072/109] Update TeachBooks-Favourites dependency version --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 0479af9..e76d771 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,4 @@ teachbooks # depends on jupyter-book # Our favourite Sphinx extensions in one line, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) -git+https://github.com/TeachBooks/TeachBooks-Favourites +git+https://github.com/TeachBooks/TeachBooks-Favourites #BUMP From 951dd32e8b1929e48a3a56c38124a3fbd529677d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 09:05:30 +0200 Subject: [PATCH 073/109] Update TeachBooks Favourites repository URL --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index e76d771..0479af9 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,4 @@ teachbooks # depends on jupyter-book # Our favourite Sphinx extensions in one line, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) -git+https://github.com/TeachBooks/TeachBooks-Favourites #BUMP +git+https://github.com/TeachBooks/TeachBooks-Favourites From e876328b7ccb45b06584e866870eeda6de849003 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 15:34:43 +0200 Subject: [PATCH 074/109] Change None to null in YAML configuration --- book/_config.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index fd475ba..2c97ae9 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -54,7 +54,7 @@ sphinx: # Options passed on to the named_colors_include_CSS: true # Default value (line can be removed), includes all CSS colours, configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html) named_colors_dark_and_light: true # Default value (line can be removed), creates dark mode colours for CSS and custom named colours, configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html) named_colors_saturation: 1.5 # Default value (line can be removed), sets saturation of CSS and custom named colours in dark mode to 1.5, configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html) - named_colors_custom_colors: None # Default value (line can be removed), defines no custom named colours (include no colour for attribution admonition of external pages), configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html) + named_colors_custom_colors: null # Default value (line can be removed), defines no custom named colours (include no colour for attribution admonition of external pages), configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html) proof_minimal_theme: false # Default value (line can be removed), uses default color scheme for admonitions part of sphinx-proof, configuration part of Sphinx-Proof (https://sphinx-proof.readthedocs.io/en/latest/options.html) sphinx_codex_name: "" # Default value (line can be removed), uses default 'Code example' as title for codex directives, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) sphinx_codex_style_from_proof: true # Default value (line can be removed), the CSS color style of the codex directive will be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) @@ -69,7 +69,7 @@ sphinx: # Options passed on to the teachbooks: attribution_location: top # Default value (line can be removed), sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) - attribution_color: None # Default value (line can be removed), uses blue colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) + attribution_color: null # Default value (line can be removed), uses blue colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) bibtex_bibfiles: - references.bib # Required for references From e8a609c5fa6c23cb85fd0341796ffee0723d2b61 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 15:36:36 +0200 Subject: [PATCH 075/109] Remove sphinx_togglebutton_selector from config --- book/_config.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/book/_config.yml b/book/_config.yml index 2c97ae9..49934f7 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -60,7 +60,6 @@ sphinx: # Options passed on to the sphinx_codex_style_from_proof: true # Default value (line can be removed), the CSS color style of the codex directive will be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) sphinx_codex_icon_from_proof: false # Default value (line can be removed), the icon of the codex directive will not be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) sphinx_codex_merge_with_proof: false # Default value (line can be removed), the codex directive will not be merged with the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) - sphinx_togglebutton_selector: ".toggle, .admonition.dropdown" # Default value (line can be removed), configures the CSS selector used to insert toggle buttons, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html togglebutton_hint: "Click to show" # Default value (line can be removed), defines hint when toggle is closed, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html togglebutton_hint_hide: "Click to hide" # Default value (line can be removed), defines hint when toggle is opened, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html togglebutton_open_on_print: true # Default value (line can be removed), opens all toggle-able content when you print, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html From 23259583f6e55b755f8e04051c996090f69123c4 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 16:00:19 +0200 Subject: [PATCH 076/109] Update _config.yml --- book/_config.yml | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index 49934f7..9c0bfa3 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,9 +1,7 @@ -title: TeachBooks template # Replace this with your own book title author: TeachBooks Team, built with TeachBooks, CC BY 4.0 - # Replace TeachBooks Teams with your own name in the line above - + # Replace TeachBooks Teams with your own name in the line above, configuratin part of JupyterBook: https://jupyterbook.org/en/stable/customize/config.html execute: - execute_notebooks: "off" # Replace this if you want don't have notebooks with output and you want to add notebook output during build + execute_notebooks: "off" # Replace this if you want don't have notebooks with output and you want to add notebook output during build, configuration part of jupyterbook: https://jupyterbook.org/en/stable/customize/config.html only_build_toc_files: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents @@ -63,6 +61,19 @@ sphinx: # Options passed on to the togglebutton_hint: "Click to show" # Default value (line can be removed), defines hint when toggle is closed, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html togglebutton_hint_hide: "Click to hide" # Default value (line can be removed), defines hint when toggle is opened, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html togglebutton_open_on_print: true # Default value (line can be removed), opens all toggle-able content when you print, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html + tippy_props: {"placement": "auto-start", "maxWidth": 500, "interactive": True, "boundary": "document.body", "appendTo": "document.body"} # Default value (line can be removed), sets tippy properties, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_add_class: null # Default value (line can be removed), adds a class name to all elements with tips, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_skip_urls: null # Default value (line can be removed), a list of URL regexes to skip, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_tip_selector: "figure, table, img, p, aside, div.admonition, div.literal-block-wrapper" # Default value (line can be removed), defines what elements tips are created for, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_skip_anchor_classes: ("headerlink", "sd-stretched-link",) # Default value (line can be removed), skips showing tooltips for anchors with these classes, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_anchor_parent_selector: null # Default value (line can be removed), only show tool tips for anchors within this select, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_enable_wikitips: true # Default value (line can be removed), enables tooltips for wikipedia links, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_enable_doitips: true # Default value (line can be removed), enables tooltips for DOI links, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_doi_api: "https://api.crossref.org/works/" # Default value (line can be removed), sets the API to use for DOI tooltips, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + #tippy_doi_template # Default value not shown (line can be removed), sets the jinja template to use for formatting DOI data to tooltips, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_custom_tips: null # Default value (line can be removed), creates custom tips, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_enable_mathjax: true # Default value (line can be removed), enables tooltips for math equations, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props + tippy_js: ("https://unpkg.com/@popperjs/core@2", "https://unpkg.com/tippy.js@6") # Default value (line can be removed), sets the Javascript required to enable tooltips, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props extra_extensions: - teachbooks_favourites # Gives you a starter package of extensions to use in your book, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) From f3e4d8b43fd51ae37742a0542bed9d175e37b067 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 17:01:47 +0200 Subject: [PATCH 077/109] Update _config.yml --- book/_config.yml | 102 +++++++++++++++++++++++++++++------------------ 1 file changed, 63 insertions(+), 39 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index 9c0bfa3..1e9576f 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,18 +1,30 @@ +# This config includes all the recommended (default) configuration options of the TeachBooks software, and a TeachBooks' selection of configuration options as provided by Jupyter Book for Jupyter Book software and Sphinx. + author: TeachBooks Team, built with TeachBooks, CC BY 4.0 # Replace TeachBooks Teams with your own name in the line above, configuratin part of JupyterBook: https://jupyterbook.org/en/stable/customize/config.html execute: - execute_notebooks: "off" # Replace this if you want don't have notebooks with output and you want to add notebook output during build, configuration part of jupyterbook: https://jupyterbook.org/en/stable/customize/config.html - -only_build_toc_files: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents - + execute_notebooks: "off" # Replace this if you want don't have notebooks with output and you want to add notebook output during build, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + cache: `_build/.jupyter_cache/` # Default value (line can be removed), sets path to the jupyter cache that will be used to store execution artifacts, doesn't work in GitHub workflow, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + exclude_patterns: [] # Default value (line can be removed), sets a list of patterns to *skip* in execution, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html), can overwritten by Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) + timeout: 30 # Default value (line can be removed), sets he maximum time (in seconds) each notebook cell is allowed to run, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + run_in_temp: false # Default value (line can be removed), disables a temporary directory was the command working directory (cwd), configuration part Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + allow_errors: false # Default value (line can be removed), all cells are always run, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + stderr_output: show # Default value (line can be removed), shows stderr output, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + +only_build_toc_files: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents, configuration part of jupyterbook: https://jupyterbook.org/en/stable/customize/config.html html: - favicon : "figures/TB_favicon.ico" # Replace this with your own favicon - baseurl : "https://.io/" # Replace this with your own URL + favicon: "figures/TB_favicon.ico" # Replace this with your own favicon, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + baseurl: "https://.io/" # Replace this with your own URL, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + use_multitoc_numbering : true # Default value (line can be removed), sets continuous numbering across parts/chapters, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + extra_footer : "" # Default value (line can be removed), sets text to be displayed underneath the footer, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) sphinx: # Options passed on to the underlying sphinx-parser + extra_extensions: # Sets a list of extensions to load by sphinx, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + - teachbooks_favourites # Gives you a starter package of extensions to use in your book, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) + local_extension: null # Sets a a list of local extensions to load by sphinx, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) config: - language: en # Defines language (English) of everything except the content itself. For Dutch: replace with `nl` + language: en # Defines language (English) of everything except the content itself. For Dutch: replace with `nl`, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) html_js_files: - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js # Required for live code, part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html) thebe_config: @@ -20,23 +32,24 @@ sphinx: # Options passed on to the exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] #exclude files which should not be accessible for live code, configuration part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html) html_theme_options: logo: - text: Template # Replace this with your own book title - image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark) - image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light) - repository_url: "https://github.com/user/repo" # Add your own repo URL here - path_to_docs: "book" # Required for edit_page_button, should be book if you're using TeachBooks package (https://github.com/TeachBooks/TeachBooks) or the TeachBooks deploy book workflow (https://teachbooks.io/manual/external/deploy-book-workflow/README.html) - repository_branch: "main" # Replace when you change the name of your published branch (required for edit_page_button) - use_edit_page_button: true # Replace with false if you don't want the edit page button (i.e. if you don't user to propose changes themselves or have a private repo) - use_repository_button: true # Replace with false if you don't want the repository button (i.e. if you have a private repo) - use_issues_button : true # Replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo) + text: Template # Replace this with your own book title, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark), configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light), configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + repository_url: "https://github.com/user/repo" # Add your own repo URL here, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + path_to_docs: "book" # Required for edit_page_button, should be book if you're using TeachBooks package (https://github.com/TeachBooks/TeachBooks) or the TeachBooks deploy book workflow (https://teachbooks.io/manual/external/deploy-book-workflow/README.html), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + repository_branch: "main" # Replace when you change the name of your published branch (required for edit_page_button), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + use_edit_page_button: true # Replace with false if you don't want the edit page button (i.e. if you don't user to propose changes themselves or have a private repo), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + use_repository_button: true # Replace with false if you don't want the repository button (i.e. if you have a private repo), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + use_issues_button : true # Replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) launch_buttons: thebe: true # Required for live code, part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html) - html_show_copyright: false # As the copyright is included in the author field - html_last_updated_fmt: '%B %-d, %Y' # Adds the date of the last update to the footer - html_static_path: ["figures"] # Add folder that contain files that need to be included, such as the location of the logo(s) + announcement: "" # Default value (line can be removed), sets a banner announcement at the top of the site, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + html_show_copyright: false # As the copyright is included in the author field, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + html_last_updated_fmt: '%B %-d, %Y' # Adds the date of the last update to the footer, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + html_static_path: ["figures"] # Add folder that contain files that need to be included, such as the location of the logo(s), configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) mathjax3_config: chtml: { - mtextInheritFont: true # To typeset text within math prettier + mtextInheritFont: true # To typeset text within math prettier, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) } patch_config: disabled-patches: [] # Default value (line can be removed), disables specific patches, configuration part of JupyterBook-Patches (https://teachbooks.io/manual/external/JupyterBook-Patches/README.html) @@ -58,28 +71,39 @@ sphinx: # Options passed on to the sphinx_codex_style_from_proof: true # Default value (line can be removed), the CSS color style of the codex directive will be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) sphinx_codex_icon_from_proof: false # Default value (line can be removed), the icon of the codex directive will not be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) sphinx_codex_merge_with_proof: false # Default value (line can be removed), the codex directive will not be merged with the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) - togglebutton_hint: "Click to show" # Default value (line can be removed), defines hint when toggle is closed, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html - togglebutton_hint_hide: "Click to hide" # Default value (line can be removed), defines hint when toggle is opened, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html - togglebutton_open_on_print: true # Default value (line can be removed), opens all toggle-able content when you print, configuration part of https://sphinx-togglebutton.readthedocs.io/en/latest/use.html - tippy_props: {"placement": "auto-start", "maxWidth": 500, "interactive": True, "boundary": "document.body", "appendTo": "document.body"} # Default value (line can be removed), sets tippy properties, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_add_class: null # Default value (line can be removed), adds a class name to all elements with tips, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_skip_urls: null # Default value (line can be removed), a list of URL regexes to skip, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_tip_selector: "figure, table, img, p, aside, div.admonition, div.literal-block-wrapper" # Default value (line can be removed), defines what elements tips are created for, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_skip_anchor_classes: ("headerlink", "sd-stretched-link",) # Default value (line can be removed), skips showing tooltips for anchors with these classes, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_anchor_parent_selector: null # Default value (line can be removed), only show tool tips for anchors within this select, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_enable_wikitips: true # Default value (line can be removed), enables tooltips for wikipedia links, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_enable_doitips: true # Default value (line can be removed), enables tooltips for DOI links, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_doi_api: "https://api.crossref.org/works/" # Default value (line can be removed), sets the API to use for DOI tooltips, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - #tippy_doi_template # Default value not shown (line can be removed), sets the jinja template to use for formatting DOI data to tooltips, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_custom_tips: null # Default value (line can be removed), creates custom tips, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_enable_mathjax: true # Default value (line can be removed), enables tooltips for math equations, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - tippy_js: ("https://unpkg.com/@popperjs/core@2", "https://unpkg.com/tippy.js@6") # Default value (line can be removed), sets the Javascript required to enable tooltips, configuration part of https://sphinx-tippy.readthedocs.io/en/latest/#confval-tippy_props - extra_extensions: - - teachbooks_favourites # Gives you a starter package of extensions to use in your book, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) + togglebutton_hint: "Click to show" # Default value (line can be removed), defines hint when toggle is closed, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html) + togglebutton_hint_hide: "Click to hide" # Default value (line can be removed), defines hint when toggle is opened, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html) + togglebutton_open_on_print: true # Default value (line can be removed), opens all toggle-able content when you print, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html) + nb_execution_includepatterns: [] # Default value (line can be removed), sets a a list of glob patterns to indicate notebooks that must be included for execution, configuration part of Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) + nb_execution_patterns_method: "only_include" # Default value (line can be removed), sets the method used when both include and exclude patterns are provided, configuration part of Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) + tippy_props: {"placement": "auto-start", "maxWidth": 500, "interactive": True, "boundary": "document.body", "appendTo": "document.body"} # Default value (line can be removed), sets tippy properties, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_add_class: null # Default value (line can be removed), adds a class name to all elements with tips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_skip_urls: "" # Default value (line can be removed), a list of URL regexes to skip, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_tip_selector: "figure, table, img, p, aside, div.admonition, div.literal-block-wrapper" # Default value (line can be removed), defines what elements tips are created for, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_skip_anchor_classes: ("headerlink", "sd-stretched-link",) # Default value (line can be removed), skips showing tooltips for anchors with these classes, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_anchor_parent_selector: null # Default value (line can be removed), only show tool tips for anchors within this select, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_enable_wikitips: true # Default value (line can be removed), enables tooltips for wikipedia links, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_enable_doitips: true # Default value (line can be removed), enables tooltips for DOI links, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_doi_api: "https://api.crossref.org/works/" # Default value (line can be removed), sets the API to use for DOI tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + #tippy_doi_template # Default value not shown (line can be removed), sets the jinja template to use for formatting DOI data to tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_custom_tips: null # Default value (line can be removed), creates custom tips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_enable_mathjax: true # Default value (line can be removed), enables tooltips for math equations, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + tippy_js: ("https://unpkg.com/@popperjs/core@2", "https://unpkg.com/tippy.js@6") # Default value (line can be removed), sets the Javascript required to enable tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) teachbooks: attribution_location: top # Default value (line can be removed), sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) attribution_color: null # Default value (line can be removed), uses blue colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) bibtex_bibfiles: - - references.bib # Required for references + - references.bib # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + +# Parse and render settings +parse: + myst_enable_extensions: # Default values (lines can be removed), sets extensions to enable in the myst parser, configuration part of MyST parser (https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) + - colon_fence + - dollarmath + - linkify + - substitution + - tasklist + myst_url_schemes: [mailto, http, https] # Default value (lines can be removed), sets URI schemes that will be recognised as external URLs in Markdown links, configuration part of MyST parser (https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) + myst_dmath_double_inline: true # Default value (lines can be removed), allows display math ($$) within an inline context, configuration part of MyST parser (https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) From 613c07257f4745e2d3c40939b87d01a844d7fd0a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 17:04:37 +0200 Subject: [PATCH 078/109] Fix cache path format in _config.yml --- book/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_config.yml b/book/_config.yml index 1e9576f..7dde32f 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -4,7 +4,7 @@ author: TeachBooks Team, built with TeachBooks Date: Sun, 14 Sep 2025 17:07:29 +0200 Subject: [PATCH 079/109] Update _config.yml --- book/_config.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index 7dde32f..d04c7f6 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -77,18 +77,18 @@ sphinx: # Options passed on to the nb_execution_includepatterns: [] # Default value (line can be removed), sets a a list of glob patterns to indicate notebooks that must be included for execution, configuration part of Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) nb_execution_patterns_method: "only_include" # Default value (line can be removed), sets the method used when both include and exclude patterns are provided, configuration part of Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) tippy_props: {"placement": "auto-start", "maxWidth": 500, "interactive": True, "boundary": "document.body", "appendTo": "document.body"} # Default value (line can be removed), sets tippy properties, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) - tippy_add_class: null # Default value (line can be removed), adds a class name to all elements with tips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) - tippy_skip_urls: "" # Default value (line can be removed), a list of URL regexes to skip, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + #tippy_add_class # Default value not shown (line can be removed), adds a class name to all elements with tips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + #tippy_skip_urls # Default value not shown (line can be removed), a list of URL regexes to skip, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) tippy_tip_selector: "figure, table, img, p, aside, div.admonition, div.literal-block-wrapper" # Default value (line can be removed), defines what elements tips are created for, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) - tippy_skip_anchor_classes: ("headerlink", "sd-stretched-link",) # Default value (line can be removed), skips showing tooltips for anchors with these classes, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) - tippy_anchor_parent_selector: null # Default value (line can be removed), only show tool tips for anchors within this select, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + #tippy_skip_anchor_classes # Default value not shown (line can be removed), skips showing tooltips for anchors with these classes, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + #tippy_anchor_parent_selector # Default value not shown (line can be removed), only show tool tips for anchors within this select, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) tippy_enable_wikitips: true # Default value (line can be removed), enables tooltips for wikipedia links, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) tippy_enable_doitips: true # Default value (line can be removed), enables tooltips for DOI links, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) tippy_doi_api: "https://api.crossref.org/works/" # Default value (line can be removed), sets the API to use for DOI tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) #tippy_doi_template # Default value not shown (line can be removed), sets the jinja template to use for formatting DOI data to tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) - tippy_custom_tips: null # Default value (line can be removed), creates custom tips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + #tippy_custom_tips # Default value not shown (line can be removed), creates custom tips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) tippy_enable_mathjax: true # Default value (line can be removed), enables tooltips for math equations, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) - tippy_js: ("https://unpkg.com/@popperjs/core@2", "https://unpkg.com/tippy.js@6") # Default value (line can be removed), sets the Javascript required to enable tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + #tippy_js # Default value not shown (line can be removed), sets the Javascript required to enable tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) teachbooks: attribution_location: top # Default value (line can be removed), sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) From 80db34707dcdedb6e5bce03b8834c874781cd8ef Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 17:13:32 +0200 Subject: [PATCH 080/109] Update table of contents with new sections --- book/_toc.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index e93a13f..2dbbc71 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -2,11 +2,13 @@ format: jb-book root: intro.md parts: - - caption: Contents + - caption: Some contents chapters: - file: some_content/overview.md sections: - file: some_content/text_and_code.ipynb + - caption: Exercises + chapters: - file: exercises.md sections: - file: exercises/001.md @@ -27,6 +29,8 @@ parts: - file: syntax_exercises/011.md - file: syntax_exercises/012.md - file: syntax_exercises/013.md + - caption: Miscellaneous + chapters: - file: references.md - file: changelog.md - file: credits.md From 3b18190d2becda14f24f810230a22f61bbf5d027 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 17:15:41 +0200 Subject: [PATCH 081/109] Update _toc.yml --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 2dbbc71..1db32a8 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -2,7 +2,7 @@ format: jb-book root: intro.md parts: - - caption: Some contents + - caption: Part with some content chapters: - file: some_content/overview.md sections: From e1b8b339df90dfa0481939a8e6e3c50f03642754 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 18:22:17 +0200 Subject: [PATCH 082/109] Set sphinx options as sphinx options --- book/_config.yml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index d04c7f6..eba762b 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -14,8 +14,6 @@ execute: only_build_toc_files: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents, configuration part of jupyterbook: https://jupyterbook.org/en/stable/customize/config.html html: - favicon: "figures/TB_favicon.ico" # Replace this with your own favicon, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - baseurl: "https://.io/" # Replace this with your own URL, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) use_multitoc_numbering : true # Default value (line can be removed), sets continuous numbering across parts/chapters, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) extra_footer : "" # Default value (line can be removed), sets text to be displayed underneath the footer, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) @@ -30,6 +28,8 @@ sphinx: # Options passed on to the thebe_config: use_thebe_lite: true # Required for live code, part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html) exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] #exclude files which should not be accessible for live code, configuration part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html) + html_favicon: "figures/TB_favicon.ico" # Replace this with your own favicon, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + html_baseurl: "https://.io/" # Replace this with your own URL, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) html_theme_options: logo: text: Template # Replace this with your own book title, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) @@ -51,6 +51,7 @@ sphinx: # Options passed on to the chtml: { mtextInheritFont: true # To typeset text within math prettier, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) } + bibtex_bibfiles: references.bib # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) patch_config: disabled-patches: [] # Default value (line can be removed), disables specific patches, configuration part of JupyterBook-Patches (https://teachbooks.io/manual/external/JupyterBook-Patches/README.html) inverter_all: true # Default value (line can be removed), inverts all figures, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html) @@ -94,9 +95,6 @@ teachbooks: attribution_location: top # Default value (line can be removed), sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) attribution_color: null # Default value (line can be removed), uses blue colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) -bibtex_bibfiles: - - references.bib # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) - # Parse and render settings parse: myst_enable_extensions: # Default values (lines can be removed), sets extensions to enable in the myst parser, configuration part of MyST parser (https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) From 0df4b0d61a01e343fe18fdce8efb42f810859a0b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 18:24:05 +0200 Subject: [PATCH 083/109] Change bibtex_bibfiles to a list format --- book/_config.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/_config.yml b/book/_config.yml index eba762b..8a6c779 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -51,7 +51,8 @@ sphinx: # Options passed on to the chtml: { mtextInheritFont: true # To typeset text within math prettier, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) } - bibtex_bibfiles: references.bib # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + bibtex_bibfiles: + - references.bib # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) patch_config: disabled-patches: [] # Default value (line can be removed), disables specific patches, configuration part of JupyterBook-Patches (https://teachbooks.io/manual/external/JupyterBook-Patches/README.html) inverter_all: true # Default value (line can be removed), inverts all figures, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html) From c5e28dae5214e9cde20648ee04dba9842eb194bb Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 18:25:38 +0200 Subject: [PATCH 084/109] Change bibtex_bibfiles format in config --- book/_config.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index 8a6c779..ead7c1c 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -51,8 +51,7 @@ sphinx: # Options passed on to the chtml: { mtextInheritFont: true # To typeset text within math prettier, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) } - bibtex_bibfiles: - - references.bib # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + bibtex_bibfiles: "references.bib" # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) patch_config: disabled-patches: [] # Default value (line can be removed), disables specific patches, configuration part of JupyterBook-Patches (https://teachbooks.io/manual/external/JupyterBook-Patches/README.html) inverter_all: true # Default value (line can be removed), inverts all figures, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html) From 81afc603733e66bcf9e4e016c2d01f79a1bba38a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 18:27:57 +0200 Subject: [PATCH 085/109] Update _config.yml --- book/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_config.yml b/book/_config.yml index ead7c1c..3a8df7f 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -51,7 +51,7 @@ sphinx: # Options passed on to the chtml: { mtextInheritFont: true # To typeset text within math prettier, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) } - bibtex_bibfiles: "references.bib" # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + bibtex_bibfiles: "./references.bib" # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) patch_config: disabled-patches: [] # Default value (line can be removed), disables specific patches, configuration part of JupyterBook-Patches (https://teachbooks.io/manual/external/JupyterBook-Patches/README.html) inverter_all: true # Default value (line can be removed), inverts all figures, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html) From 4dbc469d11f4af189d08a73c7548bbf204630f6a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 18:30:16 +0200 Subject: [PATCH 086/109] Move bibtex_bibfiles to a new format in config --- book/_config.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/_config.yml b/book/_config.yml index 3a8df7f..779ce4f 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -51,7 +51,6 @@ sphinx: # Options passed on to the chtml: { mtextInheritFont: true # To typeset text within math prettier, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) } - bibtex_bibfiles: "./references.bib" # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) patch_config: disabled-patches: [] # Default value (line can be removed), disables specific patches, configuration part of JupyterBook-Patches (https://teachbooks.io/manual/external/JupyterBook-Patches/README.html) inverter_all: true # Default value (line can be removed), inverts all figures, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html) @@ -95,6 +94,9 @@ teachbooks: attribution_location: top # Default value (line can be removed), sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) attribution_color: null # Default value (line can be removed), uses blue colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) +bibtex_bibfiles: + - references.bib # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) + # Parse and render settings parse: myst_enable_extensions: # Default values (lines can be removed), sets extensions to enable in the myst parser, configuration part of MyST parser (https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) From 96055fed99bdaecf3d20fd29eea7600a0fe71b1a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 17 Sep 2025 08:34:52 +0200 Subject: [PATCH 087/109] Update _config.yml --- book/_config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_config.yml b/book/_config.yml index 779ce4f..269ca9f 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -51,6 +51,7 @@ sphinx: # Options passed on to the chtml: { mtextInheritFont: true # To typeset text within math prettier, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) } + keep_warnings: false # Default value (line can be removed), disables showing warnings in the book, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-keep_warnings) patch_config: disabled-patches: [] # Default value (line can be removed), disables specific patches, configuration part of JupyterBook-Patches (https://teachbooks.io/manual/external/JupyterBook-Patches/README.html) inverter_all: true # Default value (line can be removed), inverts all figures, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html) From 3451860f47ae16bbd52ecc8b8a321832eea00b21 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 17 Sep 2025 11:35:52 +0200 Subject: [PATCH 088/109] Correct line numbers in configuration instructions Updated line references for configuration in exercises. --- book/exercises/003.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/exercises/003.md b/book/exercises/003.md index a53e9a4..d3d3e2e 100644 --- a/book/exercises/003.md +++ b/book/exercises/003.md @@ -18,7 +18,7 @@ author: , built with TeachBooks a 3. In the `Edit` field, change the title of your homepage which will under the logo and above the table of contents ````{admonition} Need some help? :class: tip, dropdown -The 21st line of your `_config.yml` should look like +The 35th line of your `_config.yml` should look like ```yaml text: ``` @@ -26,7 +26,7 @@ The 21st line of your `_config.yml` should look like 4. In the `Edit` field, change the repository url which will be used to allow other people to open your repository, suggest edits and open issues as shown in top right corner of the built book under {octicon}`mark-github;1em`. ````{admonition} Need some help? :class: tip, dropdown -The 24th line of your `_config.yml` should look like +The 38th line of your `_config.yml` should look like ```yaml repository_url: "https://github.com//" ``` @@ -45,4 +45,4 @@ Before moving on to the next exercise, make sure you understand the following: - What is this special `_config.yml` file? - Changes in `_config.yml` can have effect on multiple pages in the book - The `_config.yml` is generally not used for adding content -``` \ No newline at end of file +``` From 787abe2d3d7e371004a5aaf9d84e38a1cb14de76 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 17 Sep 2025 11:52:19 +0200 Subject: [PATCH 089/109] various updates --- book/_toc.yml | 6 +- book/exercises/summary.md | 6 +- .../014.md | 100 ++++++++++-------- book/extensions.md | 3 + book/live_exercises.md | 5 - book/some_content/text_and_code.ipynb | 7 ++ book/syntax_exercises/007.md | 2 +- book/syntax_exercises/008.md | 2 +- book/syntax_exercises/009.md | 2 +- book/syntax_exercises/010.md | 2 +- book/syntax_exercises/011.md | 2 +- book/syntax_exercises/012.md | 2 +- book/syntax_exercises/013.md | 3 +- 13 files changed, 78 insertions(+), 64 deletions(-) rename book/{live_exercises => extension_exercises}/014.md (63%) create mode 100644 book/extensions.md delete mode 100644 book/live_exercises.md diff --git a/book/_toc.yml b/book/_toc.yml index a4127e9..95f2bd0 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -16,7 +16,6 @@ parts: - file: exercises/005.md - file: exercises/005a.md - file: exercises/006.md - - file: exercises/007.md - file: exercises/summary - file: syntax_exercises.md sections: @@ -27,9 +26,10 @@ parts: - file: syntax_exercises/011.md - file: syntax_exercises/012.md - file: syntax_exercises/013.md - - file: live_exercises.md + - file: extensions.md sections: - - file: live_exercises/014.md + - file: exercises/007.md + - file: extension_exercises/014.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/summary.md b/book/exercises/summary.md index d3cd5b0..4810e64 100644 --- a/book/exercises/summary.md +++ b/book/exercises/summary.md @@ -15,9 +15,9 @@ Here is how these exercises relate to the workflow. | :---: | :---: | :---: | :---: | | 1 | Get and idea | 4 | Create an issue | | 2 | Create _your_ version of the book | 4 | Create a branch | -| 3 | Edit the book | 1, 2, 3, 6, 8| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | -| 4 | Check changes online | 1, 2, 3, 6, 8 | Workflows and Actions Summary | -| 5 | Repeat edit and checking | 1, 2, 3, 4, 5, 8 | Keep on doing all the steps until it's ready| +| 3 | Edit the book | 1, 2, 3, 6| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | +| 4 | Check changes online | 1, 2, 3, 6| Workflows and Actions Summary | +| 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready| | 6 | Submit for review | 5, 7 | Open and merge a Pull Request, from a branch or forks | ## Keep practicing diff --git a/book/live_exercises/014.md b/book/extension_exercises/014.md similarity index 63% rename from book/live_exercises/014.md rename to book/extension_exercises/014.md index fc336d9..0a6fdee 100644 --- a/book/live_exercises/014.md +++ b/book/extension_exercises/014.md @@ -1,6 +1,8 @@ -# Exercise 16: Custom cell tags +# Custom cell tags -With the extended functionality of live code, additional cell tags have been developed that can be added to Python code cells in your book. These tags extend the [existing Jupyter Book tags](https://jupyterbook.org/en/stable/content/metadata.html) and allow you to control how cells behave when live execution is enabled. +With live coding you can make your pages more interactive by adding live, executable code cells. This extension is already part of your TeachBooks book if you started from the template. If not, you can follow instructions [in the manual](https://teachbooks.io/manual/features/live_code.html#setting-up-python-live-coding) to enable it. The template also includes a sample page with live code enabled, which you can find [here for the website of the original template](https://teachbooks.io/template/some_content/text_and_code.html) + +With live code enabled, readers can run snippets directly in the browser, experiment with examples, and complete exercises in real time. This section will guide you through some of the main features available: additional cell tags have been developed that can be added to Python code cells in your book. These tags extend the [existing Jupyter Book tags](https://jupyterbook.org/en/stable/content/metadata.html) and allow you to control how cells behave when live execution is enabled. ::::::{topic} Exercise objective Can you apply custom cell tags to control the execution and visibility of code cells? @@ -20,9 +22,10 @@ Tags are case-sensitive. Use lowercase and match them exactly as shown above. ## Creating a notebook -There are two ways you can try this exercise, depending on whether you have an IDE installed. +There are two ways you can try this exercise, depending on whether you have an IDE installed. If you don't know what an IDE is, or don't have one installed, follow Option 2 below. -### Option 1: Using JupyterLab or VS Code (if installed) +```````{tab-set} +``````{tab-item} Option 1: Using JupyterLab or VS Code (if installed) 1. In your repository, create a new notebook file in your book directory, e.g. `book/live_code_tags.ipynb`. 2. To add a new code cell, use `python` and enter a simple code, for example: @@ -35,10 +38,10 @@ print("Hello world!") With this setup, tags can be added by opening the cell metadata (in JupyterLab or Jupyter Notebook: `View → Cell Toolbar → Tags`). +`````` +``````{tab-item} Option 2: Using Jupytext in Markdown -### Option 2: Using Jupytext in Markdown - -3. If you don’t have JupyterLab or VS Code installed, you can still add code by writing a Markdown file with a Jupytext header. At the very top of your file (e.g. `book/live_code_tags.md`), add: +1. If you don’t have JupyterLab or VS Code installed, you can still add code in a markdown file. To make sure this is recognized as an interactive code cell, you need to add a Jupytext header. At the very top of your file (e.g. `book/live_code_tags.md`), add: ```yaml --- @@ -55,7 +58,7 @@ kernelspec: --- ``` -4. Now you can insert executable code cells with tags like this: +2. Now you can insert executable code cells with tags like this: ````md ```{code-cell} ipython3 @@ -63,9 +66,17 @@ print("Hello world!") ``` ```` -With this setup, tags can be added directly into the code cell using `:tags:`. +With this setup, tags can be added directly into the code cell using `:tags:`, for example: +````md +```{code-cell} ipython3 +:tags: ["hide-cell"] +print("Hello world!") +``` +```` +`````` +``````` ## Trying the custom tags @@ -74,11 +85,11 @@ Now that you know how to create executable code cells, let’s explore the diffe ### `disable-execution-cell` -5. This tag is useful when you want a particular code cell to display content without being executed by readers. For example, let’s set up a new cell that prints the current date and time only once: +3. This tag is useful when you want a particular code cell to display content without being executed by readers. For example, let’s set up a new cell that prints the current date and time only once: -**Option 1: Using JupyterLab or VS Code** +```````{tab-set} +``````{tab-item} Option 1: Using JupyterLab or VS Code -````md ```python import datetime @@ -86,12 +97,11 @@ import datetime current_time = datetime.datetime.now() print("This notebook was last updated at:", current_time) ``` -```` *Remember to add the tag `disable-execution-cell` locally via the cell metadata (`View → Cell Toolbar → Tags`).* - -**Option 2: Using Jupytext in Markdown** +`````` +``````{tab-item} Option 2: Using Jupytext in Markdown ````md ```{code-cell} ipython3 @@ -105,13 +115,16 @@ print("This notebook was last updated at:", current_time) ``` ```` -6. Commit and rebuild your book and visit the page — notice that this particular cell can no longer be run when live code is activated. +`````` +``````` + +4. Commit and rebuild your book and visit the page — notice that this particular cell can no longer be run when live code is activated. ### `disable-execution-page` -7. This tag is useful when you want all code cells on a page to be non-executable. This is handy if the code is used to build the page or provide context, but you don’t want readers to run it themselves. Add the tag `disable-execution-page` to any of the code cells in your file. +5. This tag is useful when you want all code cells on a page to be non-executable. This is handy if the code is used to build the page or provide context, but you don’t want readers to run it themselves. Add the tag `disable-execution-page` to any of the code cells in your file. -8. Commit and rebuild your book and visit the page — none of the cells should be executable now. +6. Commit and rebuild your book and visit the page — none of the cells should be executable now. ```{note} Remove this tag again before continuing, otherwise the next tags won’t have any effect. @@ -119,11 +132,11 @@ Remove this tag again before continuing, otherwise the next tags won’t have an ### `auto-execute-page` -9. This tag is useful when you want live code to start running automatically as soon as the page is opened. This is particularly helpful when using visualizations or interactive widgets that should initialize immediately. For example, let's set up a plot: +7. This tag is useful when you want live code to start running automatically as soon as the page is opened. This is particularly helpful when using visualizations or interactive widgets that should initialize immediately. For example, let's set up a plot: -**Option 1: Using JupyterLab or VS Code** +```````{tab-set} +``````{tab-item} Option 1: Using JupyterLab or VS Code -````md ```python import matplotlib.pyplot as plt import numpy as np @@ -135,12 +148,11 @@ plt.plot(x, y) plt.title("Sine wave") plt.show() ``` -```` *Remember to add the tag `auto-execute-page` to one of the cells via the cell metadata (`View → Cell Toolbar → Tags`).* - -**Option 2: Using Jupytext in Markdown** +`````` +``````{tab-item} Option 2: Using Jupytext in Markdown ````md ```{code-cell} ipython3 @@ -158,18 +170,20 @@ plt.show() ``` ```` -10. Commit and rebuild your book and visit the page — the plot should appear automatically without needing to click the “launch” button. +`````` +``````` + +8. Commit and rebuild your book and visit the page — the plot should appear automatically without needing to click the “launch” button. ### `thebe-init` +9. The `thebe-init` tag is useful when you want a specific cell to run automatically as soon as live coding starts. This is especially helpful for initializing variables that other cells depend on. For example, let's initialize a dataset of student names and their scores: -11. The `thebe-init` tag is useful when you want a specific cell to run automatically as soon as live coding starts. This is especially helpful for initializing variables that other cells depend on. For example, let's initialize a dataset of student names and their scores: +```````{tab-set} +``````{tab-item} Option 1: Using JupyterLab or VS Code -**Option 1: Using JupyterLab or VS Code** - -````md ```python # Initialize dataset students = ["Alice", "Bob", "Charlie", "Diana"] @@ -177,12 +191,11 @@ scores = [85, 92, 78, 90] print("Initialized dataset with students and scores") ``` -```` *Remember to add the tag `thebe-init` locally via the cell metadata (`View → Cell Toolbar → Tags`).* - -**Option 2: Using Jupytext in Markdown** +`````` +``````{tab-item} Option 2: Using Jupytext in Markdown ````md ```{code-cell} ipython3 @@ -196,24 +209,25 @@ print("Initialized dataset with students and scores") ``` ```` -12. Commit and rebuild your book and visit the page — as soon as live code starts, this cell will run by itself. +`````` +``````` + +10. Commit and rebuild your book and visit the page — as soon as live code starts, this cell will run by itself. ### `thebe-remove-input-init` -13. This tag works similarly to `thebe-init`, but the input (code) is hidden from students, so they only see the output. This is useful when you want to initialize variables or datasets without showing implementation details. To try this, simply replace the previous tag `thebe-init` with `thebe-remove-input-init` in the same cell from the previous example. +11. This tag works similarly to `thebe-init`, but the input (code) is hidden from students, so they only see the output. This is useful when you want to initialize variables or datasets without showing implementation details. To try this, simply replace the previous tag `thebe-init` with `thebe-remove-input-init` in the same cell from the previous example. -14. Commit and rebuild your book and visit the page — the cell will run automatically, but students will only see the output, not the code. +12. Commit and rebuild your book and visit the page — the cell will run automatically, but students will only see the output, not the code. +13. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -15. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +14. Add a commit message. -16. Add a commit message. - -17. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). - -18. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +15. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +16. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding :class: note @@ -224,7 +238,3 @@ Before moving on, make sure you understand the following: - Which tag makes a page auto-start live code when opened? - What is the difference between `thebe-init` and `thebe-remove-input-init`? ``` - - - - diff --git a/book/extensions.md b/book/extensions.md new file mode 100644 index 0000000..6cee792 --- /dev/null +++ b/book/extensions.md @@ -0,0 +1,3 @@ +# Extension exercises + +The previous exercises introduced you to the basics of writing content for your TeachBook, as well as getting started with the syntax used. Now let’s explore how you can add functionalities to your book using extensions. TeachBooks created a variety of Sphinx extensions to enhance your book, and you can also install third-party extensions to further customize your content. diff --git a/book/live_exercises.md b/book/live_exercises.md deleted file mode 100644 index 7eee81a..0000000 --- a/book/live_exercises.md +++ /dev/null @@ -1,5 +0,0 @@ -# Live code exercises - -The previous exercises introduced you to the basics of writing content for your TeachBook, as well as getting started with the syntax used. Now let’s explore how you can make your pages more interactive by adding live, executable code cells. - -With live code enabled, readers can run snippets directly in the browser, experiment with examples, and complete exercises in real time. This section will guide you through some of the main features and options available. \ No newline at end of file diff --git a/book/some_content/text_and_code.ipynb b/book/some_content/text_and_code.ipynb index 9abffd6..d39e71b 100644 --- a/book/some_content/text_and_code.ipynb +++ b/book/some_content/text_and_code.ipynb @@ -9,6 +9,13 @@ "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "(Click {fa}`rocket` --> {guilabel}`Live Code` to activate live code on this page.)" + ] + }, { "cell_type": "code", "execution_count": 1, diff --git a/book/syntax_exercises/007.md b/book/syntax_exercises/007.md index 7b28f02..4eca185 100644 --- a/book/syntax_exercises/007.md +++ b/book/syntax_exercises/007.md @@ -1,4 +1,4 @@ -# Exercise 9: File structure by titles +# File structure by titles In this exercise you will learn how to structure your chapters. diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index fbb84b5..c4ecdda 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -1,4 +1,4 @@ -# Exercise 10: Add visual media +# Add visual media To help you illustrate your content, it can be useful to add some type of visual media such as figures, gifs or videos. If you want to add a figure/gif to your book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale). diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 9259eb2..24f534b 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -1,4 +1,4 @@ -# Exercise 11: Use equations +# Use equations In this exercise, you will learn how to write and format mathematical equations in your TeachBook, both inline and as standalone blocks. diff --git a/book/syntax_exercises/010.md b/book/syntax_exercises/010.md index 9fe7377..eb5bee4 100644 --- a/book/syntax_exercises/010.md +++ b/book/syntax_exercises/010.md @@ -1,4 +1,4 @@ -# Exercise 12: Create tables +# Create tables In this exercise, we will explore how to create and format tables in your TeachBook using Markdown and reStructuredText. diff --git a/book/syntax_exercises/011.md b/book/syntax_exercises/011.md index 868e49b..df66d21 100644 --- a/book/syntax_exercises/011.md +++ b/book/syntax_exercises/011.md @@ -1,4 +1,4 @@ -# Exercise 13: Cross-referencing content +# Cross-referencing content In this exercise, you will learn how to create references to other parts of your book, such as chapters, sections, equations, tables and figures, as well as links. diff --git a/book/syntax_exercises/012.md b/book/syntax_exercises/012.md index 77e023f..776edfb 100644 --- a/book/syntax_exercises/012.md +++ b/book/syntax_exercises/012.md @@ -1,4 +1,4 @@ -# Exercise 14: Use admonitions +# Use admonitions In this exercise, you will learn how to use admonitions to enhance the readability and structure of your TeachBook content. Admonitions are special highlighted blocks that are useful for tips, warnings, notes, and more. diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md index e8f87c7..b00149b 100644 --- a/book/syntax_exercises/013.md +++ b/book/syntax_exercises/013.md @@ -1,5 +1,4 @@ - -# Exercise 15: Adding a Bibliography +# Adding a Bibliography In this exercise, you will learn how to cite sources using the shared bibliography provided in this template, and how to control the citation style and reference formatting using `{cite}` roles and the `{bibliography}` directive. From a3bb145c7962fb4b3cb4b1d6a571e08835c29b1f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 17 Sep 2025 11:56:49 +0200 Subject: [PATCH 090/109] final updates --- book/exercises/007.md | 2 +- book/extension_exercises/014.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/exercises/007.md b/book/exercises/007.md index d505f62..fb2f46e 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -1,4 +1,4 @@ -# Exercise 8: Add extensions to your book +# Add extensions to your book TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels in an easy way. diff --git a/book/extension_exercises/014.md b/book/extension_exercises/014.md index 0a6fdee..3e716d2 100644 --- a/book/extension_exercises/014.md +++ b/book/extension_exercises/014.md @@ -58,7 +58,7 @@ kernelspec: --- ``` -2. Now you can insert executable code cells with tags like this: +2. Now you can insert executable code cells like this: ````md ```{code-cell} ipython3 From 4eb1fb0674f7bbe59ebf358f6db92eef3e188d36 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 17 Sep 2025 11:59:31 +0200 Subject: [PATCH 091/109] final --- book/extension_exercises/014.md | 2 +- book/extensions.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/extension_exercises/014.md b/book/extension_exercises/014.md index 3e716d2..8724c83 100644 --- a/book/extension_exercises/014.md +++ b/book/extension_exercises/014.md @@ -1,4 +1,4 @@ -# Custom cell tags +# Live code With live coding you can make your pages more interactive by adding live, executable code cells. This extension is already part of your TeachBooks book if you started from the template. If not, you can follow instructions [in the manual](https://teachbooks.io/manual/features/live_code.html#setting-up-python-live-coding) to enable it. The template also includes a sample page with live code enabled, which you can find [here for the website of the original template](https://teachbooks.io/template/some_content/text_and_code.html) diff --git a/book/extensions.md b/book/extensions.md index 6cee792..99aeb06 100644 --- a/book/extensions.md +++ b/book/extensions.md @@ -1,3 +1,3 @@ # Extension exercises -The previous exercises introduced you to the basics of writing content for your TeachBook, as well as getting started with the syntax used. Now let’s explore how you can add functionalities to your book using extensions. TeachBooks created a variety of Sphinx extensions to enhance your book, and you can also install third-party extensions to further customize your content. +The previous exercises introduced you to the basics of writing content for your TeachBook, as well as getting started with the syntax used. Now let’s explore how you can add functionalities to your book using extensions. TeachBooks created a variety of Sphinx extensions to enhance your book: see [the manual](https://teachbooks.io/manual/features/overview.html) for a complete overview, including [TeachBooks Favourites](https://github.com/TeachBooks/TeachBooks-Favourites) which collects a collection of our favourite Sphinx extensions. The TeachBooks Favourites collection is already included in this template. Furthermore, you can also install third-party extensions to further customize your content. From 750102c78fc1f3ee1957204a308d325e43c2ab2b Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Mon, 22 Sep 2025 19:02:26 +0200 Subject: [PATCH 092/109] part 1 --- book/extension_exercises/015.md | 38 +++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 book/extension_exercises/015.md diff --git a/book/extension_exercises/015.md b/book/extension_exercises/015.md new file mode 100644 index 0000000..12eb9e7 --- /dev/null +++ b/book/extension_exercises/015.md @@ -0,0 +1,38 @@ +# Exercise: Deploy Book Workflow + +The **Deploy Book Workflow (DBW)** automatically builds and publishes your TeachBook whenever changes are pushed to your repository. If you started your book from the TeachBooks Template, this workflow is already included. + +With this workflow, readers can see your latest book version online without manual intervention. This exercise will guide you through triggering the workflow, configuring branch-specific builds, and customising deployment options. + +::::::{topic} Exercise objective +Can you trigger, configure, and monitor the Deploy Book Workflow to publish your TeachBook automatically? +:::::: + + + +## Trigger the workflow + +1. Make a small edit in any page of your book (for example `book/intro.md`). +2. Commit the change and push it to the `main` branch. +3. Open the **Actions** tab of your repository. You should see a workflow called *Deploy Book* running. +4. When it finishes, visit the URL: + + ```` + https://.github.io// + ```` + + to see the updated book. + + +5. The workflow can also be triggered in a separate branch. Create a new branch, e.g., `draft-chapter`. +6. Push a change to this branch. +7. The DBW automatically builds a version of your book for that branch, available at: + + ```` + https://.github.io//draft-chapter/ + ```` + +```{tip} +Branch-specific builds are useful for previewing work in progress without affecting the main book. +``` + From 882279dbe5bc6366edf6c58ae3a14c539adbb49a Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 23 Sep 2025 14:55:24 +0200 Subject: [PATCH 093/109] Update 015.md --- book/extension_exercises/015.md | 90 +++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/book/extension_exercises/015.md b/book/extension_exercises/015.md index 12eb9e7..8307c81 100644 --- a/book/extension_exercises/015.md +++ b/book/extension_exercises/015.md @@ -36,3 +36,93 @@ Can you trigger, configure, and monitor the Deploy Book Workflow to publish your Branch-specific builds are useful for previewing work in progress without affecting the main book. ``` + +## Customise the workflow + +8. The behaviour of the Deploy Book Workflow can be adapted by defining **repository variables** in your GitHub repository, as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository) or using the [VS Code Extension GitHub Actions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions). + + +```{admonition} Key repository variables +| Variable | Default | Purpose | +|-----------------------|-------------|-------------------------------------------------------------------------| +| `PRIMARY_BRANCH` | `main` | Which branch appears at the root URL. | +| `BEHAVIOR_PRIMARY` | `redirect` | How the root URL behaves: `redirect`, `copy`, or `move`. | +| `BRANCH_ALIASES` | *(blank)* | Space-separated list of aliases (custom URLs) for branches. | +| `BRANCHES_TO_DEPLOY` | `*` | Which branches are deployed (all by default). | +| `BRANCHES_TO_PREPROCESS` | *(blank)* | Branches preprocessed with TeachBooks (e.g. remove draft-only content). | +| `BRANCHES_ARCHIVED` | *(blank)* | Adds a banner to old versions marking them as archived. | +``` + +```{note} +You can also edit `.github/workflows/call-deploy-book.yml` to change which branches or folders trigger deployment. +``` + + +## Common usage scenarios + +### Scenario 1 — Academic years + +```{admonition} Context +Each year you release a new version of your book for students, but older cohorts still need access. +``` + +9. Create a branch for each year (e.g. `2024`, `2025`). +10. In repository variables, set: + + * `PRIMARY_BRANCH = 2025` + * `BEHAVIOR_PRIMARY = redirect` (so the root redirects to the current year). +11. Push a change to the `2025` branch. +12. Verify the URLs: + + * `.../my_book/2025/` (this year) + * `.../my_book/2024/` (last year) + * `.../my_book/` (redirects to current year). + +```{tip} +If you want the root URL to always show a complete book instead of the in-progress year, set +`PRIMARY_BRANCH = 2024` and `BEHAVIOR_PRIMARY = copy`, and mark `2025` as archived. +``` + + +### Scenario 2 — Draft and release workflow + +```{admonition} Context +You want a public release branch, an internal draft branch, and multiple author branches for parallel work. +``` + +13. Create branches: `release`, `draft`, `author_1`, `author_2`, etc. +14. Set your GitHub default branch to `draft`. +15. In repository variables, set: + + * `PRIMARY_BRANCH = release` + * `BEHAVIOR_PRIMARY = copy`. +16. Push changes to each branch and check the URLs: + + * `.../my_book/` (release version) + * `.../my_book/draft/` (draft version) + * `.../my_book/author_1/`, etc. + +```{note} +Making `draft` the default branch ensures pull requests are tested in draft first, avoiding accidental premature releases. +``` + + +17. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +18. Add a commit message. + +19. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). + +20. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + + + +```{admonition} Check your understanding +:class: note + + +Before moving on, make sure you understand: +- How can you trigger the Deploy Book Workflow? +- What is the purpose of `PRIMARY_BRANCH` and `BEHAVIOR_PRIMARY`? +- How would you set up the workflow so that both a release and a draft version of your book are available online? +``` \ No newline at end of file From 17a8feeca46faeeae0dfd09e73afcd770ba2f67f Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 23 Sep 2025 14:55:50 +0200 Subject: [PATCH 094/109] Update _toc.yml --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index e128798..fb79f96 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -32,6 +32,7 @@ parts: sections: - file: exercises/007.md - file: extension_exercises/014.md + - file: extension_exercises/015.md - caption: Miscellaneous chapters: - file: references.md From af326c815e78e0c146755434643816898406a6a8 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 23 Sep 2025 14:58:45 +0200 Subject: [PATCH 095/109] Update 015.md --- book/extension_exercises/015.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/extension_exercises/015.md b/book/extension_exercises/015.md index 8307c81..60e6278 100644 --- a/book/extension_exercises/015.md +++ b/book/extension_exercises/015.md @@ -1,4 +1,4 @@ -# Exercise: Deploy Book Workflow +# Deploy Book Workflow The **Deploy Book Workflow (DBW)** automatically builds and publishes your TeachBook whenever changes are pushed to your repository. If you started your book from the TeachBooks Template, this workflow is already included. @@ -47,10 +47,10 @@ Branch-specific builds are useful for previewing work in progress without affect |-----------------------|-------------|-------------------------------------------------------------------------| | `PRIMARY_BRANCH` | `main` | Which branch appears at the root URL. | | `BEHAVIOR_PRIMARY` | `redirect` | How the root URL behaves: `redirect`, `copy`, or `move`. | -| `BRANCH_ALIASES` | *(blank)* | Space-separated list of aliases (custom URLs) for branches. | +| `BRANCH_ALIASES` | | Space-separated list of aliases (custom URLs) for branches. | | `BRANCHES_TO_DEPLOY` | `*` | Which branches are deployed (all by default). | -| `BRANCHES_TO_PREPROCESS` | *(blank)* | Branches preprocessed with TeachBooks (e.g. remove draft-only content). | -| `BRANCHES_ARCHIVED` | *(blank)* | Adds a banner to old versions marking them as archived. | +| `BRANCHES_TO_PREPROCESS` | | Branches preprocessed with TeachBooks (e.g. remove draft-only content). | +| `BRANCHES_ARCHIVED` | | Adds a banner to old versions marking them as archived. | ``` ```{note} From c9414cb316de2eb7df0c994ce8fa9b04b352e203 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 7 Oct 2025 19:33:07 +0200 Subject: [PATCH 096/109] Remove VS Code Extension reference from workflow section --- book/extension_exercises/015.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/book/extension_exercises/015.md b/book/extension_exercises/015.md index 60e6278..72ae3d0 100644 --- a/book/extension_exercises/015.md +++ b/book/extension_exercises/015.md @@ -39,7 +39,7 @@ Branch-specific builds are useful for previewing work in progress without affect ## Customise the workflow -8. The behaviour of the Deploy Book Workflow can be adapted by defining **repository variables** in your GitHub repository, as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository) or using the [VS Code Extension GitHub Actions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions). +8. The behaviour of the Deploy Book Workflow can be adapted by defining **repository variables** in your GitHub repository, as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository). ```{admonition} Key repository variables @@ -69,18 +69,20 @@ Each year you release a new version of your book for students, but older cohorts 9. Create a branch for each year (e.g. `2024`, `2025`). 10. In repository variables, set: - * `PRIMARY_BRANCH = 2025` - * `BEHAVIOR_PRIMARY = redirect` (so the root redirects to the current year). + - `PRIMARY_BRANCH = 2025` + - `BEHAVIOR_PRIMARY = redirect` (so the root redirects to the current year). 11. Push a change to the `2025` branch. 12. Verify the URLs: - * `.../my_book/2025/` (this year) - * `.../my_book/2024/` (last year) - * `.../my_book/` (redirects to current year). + - `.../my_book/2025/` (this year) + - `.../my_book/2024/` (last year) + - `.../my_book/` (redirects to current year). ```{tip} If you want the root URL to always show a complete book instead of the in-progress year, set -`PRIMARY_BRANCH = 2024` and `BEHAVIOR_PRIMARY = copy`, and mark `2025` as archived. +`PRIMARY_BRANCH = 2024` and `BEHAVIOR_PRIMARY = copy`, and mark `2025` as archived. However, we recommend +using redirects as students might bookmark pages. If the URL changes the next academic year their bookmark +becomes invalid or points to another page. ``` @@ -125,4 +127,4 @@ Before moving on, make sure you understand: - How can you trigger the Deploy Book Workflow? - What is the purpose of `PRIMARY_BRANCH` and `BEHAVIOR_PRIMARY`? - How would you set up the workflow so that both a release and a draft version of your book are available online? -``` \ No newline at end of file +``` From 0d904683b088c88a2abc736e78c4d959305f7a70 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 10 Oct 2025 16:56:49 +0200 Subject: [PATCH 097/109] Add external link icon and referrer settings Added configuration options for external link icons and referrer behavior. --- book/_config.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/_config.yml b/book/_config.yml index 269ca9f..9c5ee2e 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -90,6 +90,8 @@ sphinx: # Options passed on to the #tippy_custom_tips # Default value not shown (line can be removed), creates custom tips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) tippy_enable_mathjax: true # Default value (line can be removed), enables tooltips for math equations, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) #tippy_js # Default value not shown (line can be removed), sets the Javascript required to enable tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + new_tab_link_show_external_link_icon: true # Recommended value, false is default value, adds icon to external links, configuration part of sphinx-new-tab-link (https://pypi.org/project/sphinx-new-tab-link/) + new_tab_link_enable_referrer: false # Default value (line can be removed), when set to false, prevents the target site from getting information about where the hyperlink was clicked, configuration part of sphinx-new-tab-link (https://pypi.org/project/sphinx-new-tab-link/) teachbooks: attribution_location: top # Default value (line can be removed), sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) From 1dbdf0f6e48980ae683a0e2ce6c30bc4b2c7f2d0 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Fri, 10 Oct 2025 18:24:05 +0200 Subject: [PATCH 098/109] image inverter exercise --- book/_toc.yml | 1 + book/extension_exercises/016.md | 112 ++++++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 book/extension_exercises/016.md diff --git a/book/_toc.yml b/book/_toc.yml index fb79f96..68c7a8f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -33,6 +33,7 @@ parts: - file: exercises/007.md - file: extension_exercises/014.md - file: extension_exercises/015.md + - file: extension_exercises/016.md - caption: Miscellaneous chapters: - file: references.md diff --git a/book/extension_exercises/016.md b/book/extension_exercises/016.md new file mode 100644 index 0000000..ab19927 --- /dev/null +++ b/book/extension_exercises/016.md @@ -0,0 +1,112 @@ +# Image and Iframe Dark Mode Colour Inverter + +The **Sphinx-Image-Inverter** extension automatically adapts figures, images, and iframes to dark mode by inverting their colours. This ensures that visuals remain readable and consistent across light and dark themes. In this exercise, you’ll install the extension, configure its options, and experiment with enabling and disabling inversion for specific images. + +::::::{topic} Exercise objective +Can you configure the Sphinx-Image-Inverter to control how images and iframes behave in dark mode? +:::::: + +## Install and activate the extension + +```{note} +If you cloned your book from the TeachBooks Template, this extension is already included and activated. +``` + +1. Install the package using `pip`: + + ``` + pip install sphinx-image-inverter + ``` + +2. Add the dependency to your `requirements.txt` file: + + ``` + sphinx-image-inverter + ``` + +3. Enable the extension in your `_config.yml` by ading it to the list of Sphinx extra extensions: + + ```yaml + sphinx: + extra_extensions: + - sphinx_image_inverter + ``` + +4. Commit and rebuild your book — the extension is now active. By default, all images and figures will be inverted when dark mode is toggled. + + +## Configure image inversion + +You can control how and when images are inverted by adjusting parameters in `_config.yml`. + + +5. To disable inversion globally, set `inverter_all` to `false`. This disables automatic inversion for all images. + + ```yaml + sphinx: + config: + inverter_all: false + ``` + +6. To enable inversion globally, set `inverter_all` to `true`. This enables automatic inversion for all images. + + ```yaml + sphinx: + config: + inverter_all: true + ``` + +7. If you would like to selectively include or exclude specific figures or iframes from inversion the `dark-light` class can be used. Locate the markdown file that contains the image you want to exclude from inversion and add the `:class: dark-light` attribute as follows: + +```` +```{figure} images/example_plot.png +:class: dark-light +:width: 400 +``` +```` + +```{note} +When dark mode is toggled, this image will not be inverted if `inverter_all: true`. +If `inverter_all: false`, only this image will be inverted. +``` + + +8. The saturation can also be adjusted. The default colour saturation is `1.5`. Let us reduce the contrast by changing this to `1.0`: + + ```yaml + sphinx: + config: + inverter_saturation: 1.0 + ``` + +```{tip} +Try different saturation levels to see how they affect contrast in dark mode — between `1.0` (no change) and `2.0` (vivid colours) is recommended. +``` +9. It is also possible to choose to show or hide text depending on the selected theme. This is useful for adding hints or notes that depend on visibility. Try this out using the following classes: + + +```html +This message is only visible in light mode. + +This message appears only in dark mode. +``` + +10. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +11. Add a commit message. + +12. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). + +13. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you can answer: +- What does the Sphinx-Image-Inverter extension do? +- How do you disable automatic inversion for all images? +- What is the effect of the `dark-light` class? +- What happens when you change the `inverter_saturation` value? +``` + From b9d2a57db76709f9c6e55112397c038df76e9c1b Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sun, 12 Oct 2025 15:08:21 +0200 Subject: [PATCH 099/109] teachbook favourites --- book/_toc.yml | 1 + book/extension_exercises/017.md | 112 ++++++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 book/extension_exercises/017.md diff --git a/book/_toc.yml b/book/_toc.yml index 68c7a8f..03d85b8 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -34,6 +34,7 @@ parts: - file: extension_exercises/014.md - file: extension_exercises/015.md - file: extension_exercises/016.md + - file: extension_exercises/017.md - caption: Miscellaneous chapters: - file: references.md diff --git a/book/extension_exercises/017.md b/book/extension_exercises/017.md new file mode 100644 index 0000000..29b2341 --- /dev/null +++ b/book/extension_exercises/017.md @@ -0,0 +1,112 @@ +# TeachBooks Favourites + +The **TeachBooks-Favourites** extension brings together TeachBooks’ most-used and most-loved features in one convenient package. It bundles several Sphinx extensions—developed both by TeachBooks and others—into a single install, making it easier to start a new TeachBook with all recommended functionality already enabled. + +This exercise will guide you through installing the **TeachBooks-Favourites** extension, enabling it in your configuration, and exploring what it includes. + +::::::{topic} Exercise objective +Can you install and activate the TeachBooks-Favourites extension, and identify which tools it automatically enables? +:::::: + +## Explore what’s included + +The TeachBooks-Favourites bundle includes the following extensions. For more information on each extension and how to use it, see the [TeachBooks manual](https://teachbooks.io/manual/features/favourites.html#) + +| Extension | Description | +| --------------------------- | -------------------------------------------------------------- | +| Sphinx-Thebe | Enables live executable code cells. | +| JupyterBook Patches | Improves compatibility and fixes common issues in JupyterBook. | +| Download Link Replacer | Ensures consistent download button behavior. | +| Sphinx Image Inverter | Adapts images and figures for dark mode. | +| Sphinx Iframes | Embeds external content like dashboards and videos. | +| Sphinx Exercise | Supports self-assessment exercises. | +| TeachBooks Sphinx Tippy | Adds helpful tooltips to content. | +| Sphinx Named Colors | Provides colour names compatible with LaTeX and HTML. | +| Sphinx Dropdown Toggle | Creates collapsible sections and hints. | +| Sphinx Proof | Supports theorem- and proof-like blocks. | +| Sphinx Code Examples | Displays and organizes code examples clearly. | +| Sphinx Accessibility | Improves accessibility compliance for readers. | +| Sphinx Toggle Button | Toggles visibility of content blocks. | +| Notebook Execution Patterns | Defines consistent notebook execution behavior. | +| Sphinx Launch Buttons | Adds “Launch in Binder/Colab” buttons for notebooks. | +| Sphinx New Tab Link | Opens external links in a new browser tab. | + +```{note} +If you cloned your book from the TeachBooks Template, the TeachBooks-Favourites extension is **already included and activated**. +``` + +## Install the extension + +If you’re working in a custom or manually configured repository, follow these steps to install it. + +1. Install the package using `pip`: + + ``` + pip install git+https://github.com/TeachBooks/TeachBooks-Favourites + ``` + +2. Add it to your `requirements.txt`: + + ``` + git+https://github.com/TeachBooks/TeachBooks-Favourites + ``` + +3. Enable it in `_config.yml`: + + ```yaml + sphinx: + extra_extensions: + - teachbooks_favourites + ``` + +4. Commit and rebuild your book — all favourite extensions will now load automatically with their default settings. + +```{tip} +If you’re using GitHub online only (without local installation), simply edit your `_config.yml` and `requirements.txt` files directly in the browser, then commit. The next automatic build will include the extension. +``` + +## Customising your favourites + +5. If you want to use only some of the included extensions, you can remove `teachbooks_favourites` from `_config.yml` and instead add the specific extensions you need. This gives you full control over which features are loaded. Try this out with the example below: + +```yaml +sphinx: + extra_extensions: + - sphinx_image_inverter + - sphinx_iframes + - teachbooks_sphinx_tippy +``` + + +```{tip} +Start with `teachbooks_favourites` enabled — it’s a great default for beginners. As your project grows, you can refine which extensions stay active. +``` + +## Contribute your favourite + +6. Think an extension deserves a place among the favourites? You can contribute by opening an issue on [GitHub](https://github.com/TeachBooks/TeachBooks-Favourites), or submitting a **pull request** that adds it to: + + * `README.md` + * `pyproject.toml` + * `src/teachbooks_favourites/__init__.py` + +```{note} +Extensions must be stable, open-source, and enhance the TeachBooks authoring or learning experience. +``` + +7. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +8. Add a commit message. + +9. To see your changes, go to {octicon}`play` **Actions** → select the most recent workflow run → wait for it to finish → click the link under *Branches deployed* and *Primary book at root*. + +10. Don’t see your change? Press `CTRL+F5` / `Control+F5` to refresh the page. + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you can answer: +- What is the TeachBooks-Favourites extension? +- How do you enable it in `_config.yml`? +- What should you do if you only want to load a few of the extensions? +``` From c7bfc73bdee5d40946321899544326196cce96b3 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 12 Oct 2025 15:35:54 +0200 Subject: [PATCH 100/109] Clean up .gitignore by removing Python packaging entries Removed unnecessary entries related to Python packaging. --- .gitignore | 23 +---------------------- 1 file changed, 1 insertion(+), 22 deletions(-) diff --git a/.gitignore b/.gitignore index 7803c8f..ab65de5 100644 --- a/.gitignore +++ b/.gitignore @@ -3,29 +3,8 @@ __pycache__/ *.py[cod] *$py.class -# C extensions -*.so - -# Distribution / packaging +# Python .Python -build/ -develop-eggs/ -dist/ -downloads/ -eggs/ -.eggs/ -lib/ -lib64/ -parts/ -sdist/ -var/ -wheels/ -pip-wheel-metadata/ -share/python-wheels/ -*.egg-info/ -.installed.cfg -*.egg -MANIFEST .vscode/ # PyInstaller From bf26915ca0b53ca902627a0b10d2a8e8ca3cd9ea Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 12 Oct 2025 16:22:18 +0200 Subject: [PATCH 101/109] finalize --- book/_toc.yml | 2 +- book/extension_exercises/016.md | 89 +++++++++------------------ book/extension_exercises/017.md | 104 +++++++++----------------------- 3 files changed, 58 insertions(+), 137 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index 03d85b8..8229988 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -31,10 +31,10 @@ parts: - file: extensions.md sections: - file: exercises/007.md + - file: extension_exercises/017.md - file: extension_exercises/014.md - file: extension_exercises/015.md - file: extension_exercises/016.md - - file: extension_exercises/017.md - caption: Miscellaneous chapters: - file: references.md diff --git a/book/extension_exercises/016.md b/book/extension_exercises/016.md index ab19927..52aa855 100644 --- a/book/extension_exercises/016.md +++ b/book/extension_exercises/016.md @@ -1,46 +1,16 @@ # Image and Iframe Dark Mode Colour Inverter -The **Sphinx-Image-Inverter** extension automatically adapts figures, images, and iframes to dark mode by inverting their colours. This ensures that visuals remain readable and consistent across light and dark themes. In this exercise, you’ll install the extension, configure its options, and experiment with enabling and disabling inversion for specific images. +The **Sphinx-Image-Inverter** extension automatically adapts figures, images, and iframes to dark mode by inverting their colours. Meanwhile, it makes sure that a colour is still recognizable, i.e. red stays red, blue stays blue, etc. This ensures that visuals remain readable and consistent across light and dark themes. In this exercise, you’ll install the extension, configure its options, and experiment with enabling and disabling inversion for specific images. ::::::{topic} Exercise objective Can you configure the Sphinx-Image-Inverter to control how images and iframes behave in dark mode? :::::: -## Install and activate the extension - -```{note} -If you cloned your book from the TeachBooks Template, this extension is already included and activated. -``` - -1. Install the package using `pip`: - - ``` - pip install sphinx-image-inverter - ``` - -2. Add the dependency to your `requirements.txt` file: - - ``` - sphinx-image-inverter - ``` - -3. Enable the extension in your `_config.yml` by ading it to the list of Sphinx extra extensions: - - ```yaml - sphinx: - extra_extensions: - - sphinx_image_inverter - ``` - -4. Commit and rebuild your book — the extension is now active. By default, all images and figures will be inverted when dark mode is toggled. - - -## Configure image inversion +# Configure image inversion You can control how and when images are inverted by adjusting parameters in `_config.yml`. - -5. To disable inversion globally, set `inverter_all` to `false`. This disables automatic inversion for all images. +1. To disable inversion globally, set `inverter_all` to `false`. This disables automatic inversion for all images. This is especially useful if your images are photos which won't look good when inverted. ```yaml sphinx: @@ -48,7 +18,7 @@ You can control how and when images are inverted by adjusting parameters in `_co inverter_all: false ``` -6. To enable inversion globally, set `inverter_all` to `true`. This enables automatic inversion for all images. +2. To enable inversion globally, set `inverter_all` to `true`. This enables automatic inversion for all images. This is useful if your images are mostly diagrams or plots which benefit from inversion. ```yaml sphinx: @@ -56,22 +26,22 @@ You can control how and when images are inverted by adjusting parameters in `_co inverter_all: true ``` -7. If you would like to selectively include or exclude specific figures or iframes from inversion the `dark-light` class can be used. Locate the markdown file that contains the image you want to exclude from inversion and add the `:class: dark-light` attribute as follows: +3. If you would like to selectively include or exclude specific figures or iframes from inversion the `dark-light` class can be used. Locate the markdown file that contains the image you want to exclude from inversion and add the `:class: dark-light` attribute as follows: -```` -```{figure} images/example_plot.png -:class: dark-light -:width: 400 -``` -```` + ````md + ```{figure} images/example_plot.png + :class: dark-light + :width: 400 + ``` + ```` -```{note} -When dark mode is toggled, this image will not be inverted if `inverter_all: true`. -If `inverter_all: false`, only this image will be inverted. -``` + ```{note} + When dark mode is toggled, this image will not be inverted if `inverter_all: true`. + If `inverter_all: false`, only this image will be inverted. + ``` -8. The saturation can also be adjusted. The default colour saturation is `1.5`. Let us reduce the contrast by changing this to `1.0`: +4. The saturation can also be adjusted. The default colour saturation is `1.5`. Let us reduce the contrast by changing this to `1.0`: ```yaml sphinx: @@ -79,25 +49,25 @@ If `inverter_all: false`, only this image will be inverted. inverter_saturation: 1.0 ``` -```{tip} -Try different saturation levels to see how they affect contrast in dark mode — between `1.0` (no change) and `2.0` (vivid colours) is recommended. -``` -9. It is also possible to choose to show or hide text depending on the selected theme. This is useful for adding hints or notes that depend on visibility. Try this out using the following classes: + ```{tip} + Try different saturation levels to see how they affect contrast in dark mode — between `1.0` (no change) and `2.0` (vivid colours) is recommended. + ``` +5. It is also possible to choose to show or hide text depending on the selected theme. This is useful for adding hints or notes that depend on visibility. Try this out using the following classes: -```html -This message is only visible in light mode. + ```html + This message is only visible in light mode. -This message appears only in dark mode. -``` + This message appears only in dark mode. + ``` -10. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -11. Add a commit message. +7. Add a commit message. -12. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +8. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). -13. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding @@ -108,5 +78,4 @@ Before moving on, make sure you can answer: - How do you disable automatic inversion for all images? - What is the effect of the `dark-light` class? - What happens when you change the `inverter_saturation` value? -``` - +``` \ No newline at end of file diff --git a/book/extension_exercises/017.md b/book/extension_exercises/017.md index 29b2341..2eaee5b 100644 --- a/book/extension_exercises/017.md +++ b/book/extension_exercises/017.md @@ -10,97 +10,49 @@ Can you install and activate the TeachBooks-Favourites extension, and identify w ## Explore what’s included -The TeachBooks-Favourites bundle includes the following extensions. For more information on each extension and how to use it, see the [TeachBooks manual](https://teachbooks.io/manual/features/favourites.html#) - -| Extension | Description | -| --------------------------- | -------------------------------------------------------------- | -| Sphinx-Thebe | Enables live executable code cells. | -| JupyterBook Patches | Improves compatibility and fixes common issues in JupyterBook. | -| Download Link Replacer | Ensures consistent download button behavior. | -| Sphinx Image Inverter | Adapts images and figures for dark mode. | -| Sphinx Iframes | Embeds external content like dashboards and videos. | -| Sphinx Exercise | Supports self-assessment exercises. | -| TeachBooks Sphinx Tippy | Adds helpful tooltips to content. | -| Sphinx Named Colors | Provides colour names compatible with LaTeX and HTML. | -| Sphinx Dropdown Toggle | Creates collapsible sections and hints. | -| Sphinx Proof | Supports theorem- and proof-like blocks. | -| Sphinx Code Examples | Displays and organizes code examples clearly. | -| Sphinx Accessibility | Improves accessibility compliance for readers. | -| Sphinx Toggle Button | Toggles visibility of content blocks. | -| Notebook Execution Patterns | Defines consistent notebook execution behavior. | -| Sphinx Launch Buttons | Adds “Launch in Binder/Colab” buttons for notebooks. | -| Sphinx New Tab Link | Opens external links in a new browser tab. | +The TeachBooks-Favourites bundle includes many extensions. For more information on each extension and how to use it, see the [TeachBooks manual](https://teachbooks.io/manual/features/favourites.html#) ```{note} If you cloned your book from the TeachBooks Template, the TeachBooks-Favourites extension is **already included and activated**. ``` -## Install the extension - -If you’re working in a custom or manually configured repository, follow these steps to install it. - -1. Install the package using `pip`: - - ``` - pip install git+https://github.com/TeachBooks/TeachBooks-Favourites - ``` - -2. Add it to your `requirements.txt`: - - ``` - git+https://github.com/TeachBooks/TeachBooks-Favourites - ``` - -3. Enable it in `_config.yml`: - - ```yaml - sphinx: - extra_extensions: - - teachbooks_favourites - ``` - -4. Commit and rebuild your book — all favourite extensions will now load automatically with their default settings. - -```{tip} -If you’re using GitHub online only (without local installation), simply edit your `_config.yml` and `requirements.txt` files directly in the browser, then commit. The next automatic build will include the extension. -``` - ## Customising your favourites -5. If you want to use only some of the included extensions, you can remove `teachbooks_favourites` from `_config.yml` and instead add the specific extensions you need. This gives you full control over which features are loaded. Try this out with the example below: +1. The TeachBooks template contains all the configuration options for all of the extensions included in TeachBooks-Favourites. Open `_config.yml` and scroll to the `sphinx` section to see the options. -```yaml -sphinx: - extra_extensions: - - sphinx_image_inverter - - sphinx_iframes - - teachbooks_sphinx_tippy -``` +2. If you want to use only some of the included extensions, you can remove `teachbooks_favourites` from `_config.yml` and instead add the specific extensions you need. This gives you full control over which features are loaded. Try this out with the example below: + ```yaml + sphinx: + extra_extensions: + - sphinx_image_inverter + - sphinx_iframes + - teachbooks_sphinx_tippy + ``` -```{tip} -Start with `teachbooks_favourites` enabled — it’s a great default for beginners. As your project grows, you can refine which extensions stay active. -``` + ```{tip} + Start with `teachbooks_favourites` enabled — it’s a great default for beginners. As your project grows, you can refine which extensions stay active. + ``` + +3. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +4. Add a commit message. + +5. To see your changes, go to {octicon}`play` **Actions** → select the most recent workflow run → wait for it to finish → click the link under *Branches deployed* and *Primary book at root*. + +6. You should see that the accessibility button (from `sphinx_accessibility`) is now gone. ## Contribute your favourite -6. Think an extension deserves a place among the favourites? You can contribute by opening an issue on [GitHub](https://github.com/TeachBooks/TeachBooks-Favourites), or submitting a **pull request** that adds it to: +7. Think an extension deserves a place among the favourites? You can contribute by opening an issue on [GitHub](https://github.com/TeachBooks/TeachBooks-Favourites), or add it yourself by submitting a **pull request** that adds it to: - * `README.md` - * `pyproject.toml` - * `src/teachbooks_favourites/__init__.py` + - `README.md` + - `pyproject.toml` + - `src/teachbooks_favourites/__init__.py` -```{note} -Extensions must be stable, open-source, and enhance the TeachBooks authoring or learning experience. -``` - -7. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. - -8. Add a commit message. - -9. To see your changes, go to {octicon}`play` **Actions** → select the most recent workflow run → wait for it to finish → click the link under *Branches deployed* and *Primary book at root*. - -10. Don’t see your change? Press `CTRL+F5` / `Control+F5` to refresh the page. + ```{note} + Extensions must be stable, open-source, and enhance the TeachBooks authoring or learning experience. + ``` ```{admonition} Check your understanding :class: note From a8c51ede4930797ff3575d2c3e45e5ee752d9d3b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 12 Oct 2025 16:25:31 +0200 Subject: [PATCH 102/109] Update 016.md --- book/extension_exercises/016.md | 1 - 1 file changed, 1 deletion(-) diff --git a/book/extension_exercises/016.md b/book/extension_exercises/016.md index 52aa855..bfbbf05 100644 --- a/book/extension_exercises/016.md +++ b/book/extension_exercises/016.md @@ -40,7 +40,6 @@ You can control how and when images are inverted by adjusting parameters in `_co If `inverter_all: false`, only this image will be inverted. ``` - 4. The saturation can also be adjusted. The default colour saturation is `1.5`. Let us reduce the contrast by changing this to `1.0`: ```yaml From 20a3b0ecfbd2e214153eac998ef1c7748f864c42 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 13 Oct 2025 11:06:51 +0200 Subject: [PATCH 103/109] Remove external link configuration options Removed configuration options for external link icon and referrer. --- book/_config.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index 9c5ee2e..269ca9f 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -90,8 +90,6 @@ sphinx: # Options passed on to the #tippy_custom_tips # Default value not shown (line can be removed), creates custom tips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) tippy_enable_mathjax: true # Default value (line can be removed), enables tooltips for math equations, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) #tippy_js # Default value not shown (line can be removed), sets the Javascript required to enable tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) - new_tab_link_show_external_link_icon: true # Recommended value, false is default value, adds icon to external links, configuration part of sphinx-new-tab-link (https://pypi.org/project/sphinx-new-tab-link/) - new_tab_link_enable_referrer: false # Default value (line can be removed), when set to false, prevents the target site from getting information about where the hyperlink was clicked, configuration part of sphinx-new-tab-link (https://pypi.org/project/sphinx-new-tab-link/) teachbooks: attribution_location: top # Default value (line can be removed), sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) From 0527e30da4435c1ba2d2af01040c56100a0b710f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 20 Oct 2025 16:38:17 +0200 Subject: [PATCH 104/109] add more configuration options, including toc --- book/_config.yml | 11 ++++++----- book/_toc.yml | 7 ++++++- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/book/_config.yml b/book/_config.yml index 269ca9f..4453ecc 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -10,11 +10,9 @@ execute: run_in_temp: false # Default value (line can be removed), disables a temporary directory was the command working directory (cwd), configuration part Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) allow_errors: false # Default value (line can be removed), all cells are always run, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) stderr_output: show # Default value (line can be removed), shows stderr output, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - -only_build_toc_files: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents, configuration part of jupyterbook: https://jupyterbook.org/en/stable/customize/config.html html: - use_multitoc_numbering : true # Default value (line can be removed), sets continuous numbering across parts/chapters, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + use_multitoc_numbering : true # Default value (line can be removed), sets continuous numbering across parts/chapters, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html). Same functionality per section can be defined with sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) extra_footer : "" # Default value (line can be removed), sets text to be displayed underneath the footer, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) sphinx: # Options passed on to the underlying sphinx-parser @@ -52,6 +50,8 @@ sphinx: # Options passed on to the mtextInheritFont: true # To typeset text within math prettier, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) } keep_warnings: false # Default value (line can be removed), disables showing warnings in the book, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-keep_warnings) + external_toc_exclude_missing: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents, configuration part of jupyterbook, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) + external_toc_path: "_toc.yml" # Default value (line can be removed), sets path to the table of contents file, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) patch_config: disabled-patches: [] # Default value (line can be removed), disables specific patches, configuration part of JupyterBook-Patches (https://teachbooks.io/manual/external/JupyterBook-Patches/README.html) inverter_all: true # Default value (line can be removed), inverts all figures, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html) @@ -72,8 +72,8 @@ sphinx: # Options passed on to the sphinx_codex_style_from_proof: true # Default value (line can be removed), the CSS color style of the codex directive will be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) sphinx_codex_icon_from_proof: false # Default value (line can be removed), the icon of the codex directive will not be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) sphinx_codex_merge_with_proof: false # Default value (line can be removed), the codex directive will not be merged with the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html) - togglebutton_hint: "Click to show" # Default value (line can be removed), defines hint when toggle is closed, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html) - togglebutton_hint_hide: "Click to hide" # Default value (line can be removed), defines hint when toggle is opened, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html) + #togglebutton_hint: "Click to show" # Displayed when the toggle is closed, overrides translated hint, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html) + #togglebutton_hint_hide: "Click to hide" # Displayed when the toggle is opened, overrides translated hint, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html) togglebutton_open_on_print: true # Default value (line can be removed), opens all toggle-able content when you print, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html) nb_execution_includepatterns: [] # Default value (line can be removed), sets a a list of glob patterns to indicate notebooks that must be included for execution, configuration part of Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) nb_execution_patterns_method: "only_include" # Default value (line can be removed), sets the method used when both include and exclude patterns are provided, configuration part of Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) @@ -91,6 +91,7 @@ sphinx: # Options passed on to the tippy_enable_mathjax: true # Default value (line can be removed), enables tooltips for math equations, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) #tippy_js # Default value not shown (line can be removed), sets the Javascript required to enable tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html) + teachbooks: attribution_location: top # Default value (line can be removed), sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) attribution_color: null # Default value (line can be removed), uses blue colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html) diff --git a/book/_toc.yml b/book/_toc.yml index 8229988..4065666 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -1,8 +1,13 @@ +# Configuration of _toc.yml file is explained in detail here: https://sphinx-external-toc.readthedocs.io/en/latest/user_guide/sphinx.html + format: jb-book root: intro.md parts: - - caption: Part with some content + - caption: Part with some content # A title for the whole the subtree, e.g. shown above the subtree in ToCs, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) + numbered: false # Whether to number the chapters/sections in this part, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) + style: numerical # Style of numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options) + restart_numbering: false # Whether to restart numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options) chapters: - file: some_content/overview.md sections: From a567a11518320d4268642014368d8cb955d76ba5 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 20 Oct 2025 16:39:10 +0200 Subject: [PATCH 105/109] Clarify default values in _toc.yml comments Updated comments in book/_toc.yml to indicate that certain configuration options are set to their default values and can be removed if desired. No functional changes to the table of contents structure. --- book/_toc.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index 4065666..7d073f7 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -5,9 +5,9 @@ root: intro.md parts: - caption: Part with some content # A title for the whole the subtree, e.g. shown above the subtree in ToCs, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) - numbered: false # Whether to number the chapters/sections in this part, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) - style: numerical # Style of numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options) - restart_numbering: false # Whether to restart numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options) + numbered: false # Default value (line can be removed), whether to number the chapters/sections in this part, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) + style: numerical # Default value (line can be removed), sstyle of numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options) + restart_numbering: false # Default value (line can be removed), whether to restart numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options) chapters: - file: some_content/overview.md sections: From 10e0ef5f0bf6737d913da827fb196c2a1fd8487d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 20 Oct 2025 16:58:47 +0200 Subject: [PATCH 106/109] Update _toc.yml --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 7d073f7..2de2bae 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -1,4 +1,4 @@ -# Configuration of _toc.yml file is explained in detail here: https://sphinx-external-toc.readthedocs.io/en/latest/user_guide/sphinx.html +# Configuration of _toc.yml file is explained in detail here: https://jupyterbook.org/en/stable/structure/toc.html and https://sphinx-external-toc.readthedocs.io/en/latest/user_guide/sphinx.html format: jb-book root: intro.md From 00bfd5305fc5f40527094240296f63799c76ca2d Mon Sep 17 00:00:00 2001 From: Dennis den Ouden-van der Horst <49307154+douden@users.noreply.github.com> Date: Mon, 20 Oct 2025 17:02:45 +0200 Subject: [PATCH 107/109] Update _toc.yml --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 2de2bae..23fa359 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -6,7 +6,7 @@ root: intro.md parts: - caption: Part with some content # A title for the whole the subtree, e.g. shown above the subtree in ToCs, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) numbered: false # Default value (line can be removed), whether to number the chapters/sections in this part, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) - style: numerical # Default value (line can be removed), sstyle of numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options) + style: numerical # Default value (line can be removed), style of numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options) restart_numbering: false # Default value (line can be removed), whether to restart numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options) chapters: - file: some_content/overview.md From 6acb3f7d1ca77626d7bd9a58c3fa7e7a88ff10ea Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 31 Oct 2025 16:28:40 +0100 Subject: [PATCH 108/109] Revise GitHub Pages activation and workflow steps Updated instructions for activating GitHub Pages and re-running workflows. --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index fe12d18..86a8318 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,6 @@ How to use the template is demonstrated in the figure below, all steps are elabo ![Demonstration for a public repository](https://github.com/TeachBooks/template_figures/blob/main/teachbooks-template.gif?raw=true) Video available [here](https://youtu.be/nN3Oi_MVvF0) - 1. To get started making your TeachBook with our functionalities, use the [template TeachBook](https://github.com/TeachBooks/main/template) as template: ![Use template](https://github.com/TeachBooks/template_figures/blob/main/use_template.png?raw=true) @@ -24,7 +23,7 @@ Video available [here](https://youtu.be/nN3Oi_MVvF0) ![Activate GitHub Pages](https://github.com/TeachBooks/template_figures/blob/main/set_up_pages.png?raw=true) -5. Make an edit to the TeachBook by editing and committing changes to one of the files in the `book/` subdirectory (available under `Code`). Now checkout the progress of the publishing workflow under `Actions` - `All workflows` - `call-deploy-book` -``. Remember, the first commit which is there has failed because GitHub Pages wasn't activated at the time of `Initial commit`, you could also re-run that job if you don't want to make an edit. You can do so by running the workflow from `Actions` - `All workflows` - `call-deploy-book` - `Initial commit` - `Re-run all jobs` - `Re-run jobs`: +5. Now checkout the progress of the publishing workflow under `Actions` - `All workflows` - `call-deploy-book` -``. The first commit which is there might have failed because GitHub Pages wasn't activated at the time of `Initial commit`. Re-run that job from `Actions` - `All workflows` - `call-deploy-book` - `Initial commit` - `Re-run all jobs` - `Re-run jobs`: ![Action](https://github.com/TeachBooks/template_figures/blob/main/action_re-run.jpeg?raw=true) From fa19165fecd8278abbdb28aa9fdb71284c1d4ac5 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 3 Nov 2025 13:36:54 +0100 Subject: [PATCH 109/109] fix broken JB links --- book/exercises/001.md | 2 +- book/exercises/003.md | 2 +- book/syntax_exercises.md | 2 +- book/syntax_exercises/007.md | 2 +- book/syntax_exercises/008.md | 2 +- book/syntax_exercises/009.md | 2 +- book/syntax_exercises/011.md | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/book/exercises/001.md b/book/exercises/001.md index cf25ea8..b237f10 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -8,7 +8,7 @@ Can you add some content to the intro page? :::::: 1. Go to the the file `book/intro.md` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` -2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this! +2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/v1/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this! 3. Click `Commit changes` 4. Add a message and description of your change. With this `commit` you save your changes to the git-timeline. Any commit can always be reverted. Therefore, it's useful to shortly explain what is included in your commit. Later on, you'll make commits which may contain changes to many different files. In that case, a descriptive commit message and description is even more useful! 5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one) diff --git a/book/exercises/003.md b/book/exercises/003.md index d3d3e2e..e2c630a 100644 --- a/book/exercises/003.md +++ b/book/exercises/003.md @@ -12,7 +12,7 @@ Can you edit the repository url defined in the `_config.yml`, change the title s :class: tip, dropdown The first line of your `_config.yml` should look like ```yaml -author: , built with TeachBooks and Jupyter Book, CC BY 4.0 +author: , built with TeachBooks and Jupyter Book, CC BY 4.0 ``` ```` 3. In the `Edit` field, change the title of your homepage which will under the logo and above the table of contents diff --git a/book/syntax_exercises.md b/book/syntax_exercises.md index b8b49ef..9f43c06 100644 --- a/book/syntax_exercises.md +++ b/book/syntax_exercises.md @@ -4,4 +4,4 @@ The previous exercise guide you through making your own book following the Teach As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In Jupyter Book, `.md` files contain text-based content with formatting, while `ipynb` files contain both text and executable code cells. `.md` files are much easier to edit online, so let's start with those! -The more you write, the more different types of content you'll want to use. [JupyterBook itself provides a cheatsheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) which will come in handy! \ No newline at end of file +The more you write, the more different types of content you'll want to use. [JupyterBook itself provides a cheatsheet](https://jupyterbook.org/v1/reference/cheatsheet.html) which will come in handy! \ No newline at end of file diff --git a/book/syntax_exercises/007.md b/book/syntax_exercises/007.md index 4eca185..4c86208 100644 --- a/book/syntax_exercises/007.md +++ b/book/syntax_exercises/007.md @@ -8,7 +8,7 @@ Can you structure your page with a title and (sub)sections? ```{tip} -More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). +More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyterbook.org/v1/reference/cheatsheet.html). ``` diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index c4ecdda..0cca807 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -22,7 +22,7 @@ Unless you are using a file format like `*.svg`, the raw contents of a visual me 4. Now let's add the figure to a chapter. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the same branch as where you've added your figure. -5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/figures.html#figure-parameters)): +5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the [JupyterBook documentation](https://jupyterbook.org/v1/content/figures.html#figure-parameters)): ````md ```{figure} figures/.png diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 24f534b..1da471c 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -7,7 +7,7 @@ Can you write and format equations correctly in your book? :::::: ```{tip} -Using properly formatted equations makes mathematical expressions clearer and more professional. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/math.html). +Using properly formatted equations makes mathematical expressions clearer and more professional. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/v1/content/math.html). ``` ## Writing equations diff --git a/book/syntax_exercises/011.md b/book/syntax_exercises/011.md index df66d21..f04631e 100644 --- a/book/syntax_exercises/011.md +++ b/book/syntax_exercises/011.md @@ -7,7 +7,7 @@ Can you create internal references to other sections, equations, tables, figures :::::: ```{tip} -Referencing elements properly ensures that readers can navigate your book more easily. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/references.html). +Referencing elements properly ensures that readers can navigate your book more easily. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/v1/content/references.html). ``` ## Referencing a Chapter or Section