From 0a2f1514896696cb811c888bcd2c658ccdcfabd9 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sun, 7 Sep 2025 13:29:02 +0200 Subject: [PATCH 1/8] 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 2/8] 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 3/8] 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 4/8] 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 5/8] 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 787abe2d3d7e371004a5aaf9d84e38a1cb14de76 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 17 Sep 2025 11:52:19 +0200 Subject: [PATCH 6/8] 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 7/8] 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 8/8] 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.