From 0a2f1514896696cb811c888bcd2c658ccdcfabd9 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sun, 7 Sep 2025 13:29:02 +0200 Subject: [PATCH] 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.