Merge pull request #87 from TeachBooks/live_code

Live code exercise 1

Author: Tom-van-Woudenberg

book/_toc.yml

@@ -18,7 +18,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:
@@ -29,6 +28,10 @@ parts:
       - file: syntax_exercises/011.md
       - file: syntax_exercises/012.md
       - file: syntax_exercises/013.md
+    - file: extensions.md
+      sections:
+      - file: exercises/007.md
+      - file: extension_exercises/014.md
   - caption: Miscellaneous
     chapters:
     - file: references.md

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.
 

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

book/extension_exercises/014.md

@@ -0,0 +1,240 @@
+# 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)
+
+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?
+::::::
+
+## 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
+
+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.
+
+```````{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:
+
+````md
+```python
+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 
+
+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
+---
+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
+---
+```
+
+2. Now you can insert executable code cells like this:
+
+````md
+```{code-cell} ipython3
+print("Hello world!")
+```
+````
+
+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
+
+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`
+
+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:
+
+```````{tab-set}
+``````{tab-item} Option 1: Using JupyterLab or VS Code
+
+```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)
+```
+
+*Remember to add the tag `disable-execution-cell` locally via the cell metadata (`View → Cell Toolbar → Tags`).*
+
+``````
+``````{tab-item} 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)
+```
+````
+
+``````
+```````
+
+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`
+
+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. 
+
+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.
+```
+
+### `auto-execute-page`
+
+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:
+
+```````{tab-set}
+``````{tab-item} Option 1: Using JupyterLab or VS Code
+
+```python
+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()
+```
+
+*Remember to add the tag `auto-execute-page` to one of the cells via the cell metadata (`View → Cell Toolbar → Tags`).*
+
+``````
+``````{tab-item} 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()
+```
+````
+
+``````
+```````
+
+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:
+
+```````{tab-set}
+``````{tab-item} Option 1: Using JupyterLab or VS Code
+
+```python
+# Initialize dataset
+students = ["Alice", "Bob", "Charlie", "Diana"]
+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`).*
+
+``````
+``````{tab-item} 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")
+```
+````
+
+
+``````
+```````
+
+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`
+
+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.
+
+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.
+
+14. Add a commit message.
+
+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
+
+Before moving on, make sure you understand the following:
+- 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`?  
+```

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: 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.

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,

book/syntax_exercises/007.md

@@ -1,4 +1,4 @@
-# Exercise 7: File structure by titles
+# File structure by titles
 
 In this exercise you will learn how to structure your chapters.
 

book/syntax_exercises/008.md

@@ -1,4 +1,4 @@
-# Exercise 8: 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).
 

book/syntax_exercises/009.md

@@ -1,4 +1,4 @@
-# Exercise 9: 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.
 

book/syntax_exercises/010.md

@@ -1,4 +1,4 @@
-# Exercise 10: Create tables
+# Create tables
 
 In this exercise, we will explore how to create and format tables in your TeachBook using Markdown and reStructuredText.