mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-12 22:25:52 +00:00
86 lines
4 KiB
Markdown
86 lines
4 KiB
Markdown
# 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`?
|
||
```
|
||
|