template/book/live_exercises/014.md

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

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:

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+F5to 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:

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.

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.

: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`?