admin2/template
1
0
Fork 0
mirror of https://github.com/TeachBooks/template.git synced 2026-11-13 14:45:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

finalize

Browse source
This commit is contained in:
Tom van Woudenberg 2025-10-12 16:22:18 +02:00
parent b9d2a57db7
commit bf26915ca0
3 changed files with 58 additions and 137 deletions
Download patch file Download diff file Expand all files Collapse all files

104
book/extension_exercises/017.md
View file

@ -10,97 +10,49 @@ Can you install and activate the TeachBooks-Favourites extension, and identify w
## Explore what’s included
The TeachBooks-Favourites bundle includes the following extensions. For more information on each extension and how to use it, see the [TeachBooks manual](https://teachbooks.io/manual/features/favourites.html#)
| Extension | Description |
| --------------------------- | -------------------------------------------------------------- |
| Sphinx-Thebe | Enables live executable code cells. |
| JupyterBook Patches | Improves compatibility and fixes common issues in JupyterBook. |
| Download Link Replacer | Ensures consistent download button behavior. |
| Sphinx Image Inverter | Adapts images and figures for dark mode. |
| Sphinx Iframes | Embeds external content like dashboards and videos. |
| Sphinx Exercise | Supports self-assessment exercises. |
| TeachBooks Sphinx Tippy | Adds helpful tooltips to content. |
| Sphinx Named Colors | Provides colour names compatible with LaTeX and HTML. |
| Sphinx Dropdown Toggle | Creates collapsible sections and hints. |
| Sphinx Proof | Supports theorem- and proof-like blocks. |
| Sphinx Code Examples | Displays and organizes code examples clearly. |
| Sphinx Accessibility | Improves accessibility compliance for readers. |
| Sphinx Toggle Button | Toggles visibility of content blocks. |
| Notebook Execution Patterns | Defines consistent notebook execution behavior. |
| Sphinx Launch Buttons | Adds “Launch in Binder/Colab” buttons for notebooks. |
| Sphinx New Tab Link | Opens external links in a new browser tab. |
The TeachBooks-Favourites bundle includes many extensions. For more information on each extension and how to use it, see the [TeachBooks manual](https://teachbooks.io/manual/features/favourites.html#)
```{note}
If you cloned your book from the TeachBooks Template, the TeachBooks-Favourites extension is **already included and activated**.
```
## Install the extension
If you’re working in a custom or manually configured repository, follow these steps to install it.
1. Install the package using `pip`:
```
pip install git+https://github.com/TeachBooks/TeachBooks-Favourites
```
2. Add it to your `requirements.txt`:
```
git+https://github.com/TeachBooks/TeachBooks-Favourites
```
3. Enable it in `_config.yml`:
```yaml
sphinx:
extra_extensions:
- teachbooks_favourites
```
4. Commit and rebuild your book — all favourite extensions will now load automatically with their default settings.
```{tip}
If you’re using GitHub online only (without local installation), simply edit your `_config.yml` and `requirements.txt` files directly in the browser, then commit. The next automatic build will include the extension.
```
## Customising your favourites
5. If you want to use only some of the included extensions, you can remove `teachbooks_favourites` from `_config.yml` and instead add the specific extensions you need. This gives you full control over which features are loaded. Try this out with the example below:
1. The TeachBooks template contains all the configuration options for all of the extensions included in TeachBooks-Favourites. Open `_config.yml` and scroll to the `sphinx` section to see the options.
```yaml
sphinx:
extra_extensions:
- sphinx_image_inverter
- sphinx_iframes
- teachbooks_sphinx_tippy
```
2. If you want to use only some of the included extensions, you can remove `teachbooks_favourites` from `_config.yml` and instead add the specific extensions you need. This gives you full control over which features are loaded. Try this out with the example below:
```yaml
sphinx:
extra_extensions:
- sphinx_image_inverter
- sphinx_iframes
- teachbooks_sphinx_tippy
```
```{tip}
Start with `teachbooks_favourites` enabled — it’s a great default for beginners. As your project grows, you can refine which extensions stay active.
```
```{tip}
Start with `teachbooks_favourites` enabled — it’s a great default for beginners. As your project grows, you can refine which extensions stay active.
```
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** → select the most recent workflow run → wait for it to finish → click the link under *Branches deployed* and *Primary book at root*.
6. You should see that the accessibility button (from `sphinx_accessibility`) is now gone.
## Contribute your favourite
6. Think an extension deserves a place among the favourites? You can contribute by opening an issue on [GitHub](https://github.com/TeachBooks/TeachBooks-Favourites), or submitting a **pull request** that adds it to:
7. Think an extension deserves a place among the favourites? You can contribute by opening an issue on [GitHub](https://github.com/TeachBooks/TeachBooks-Favourites), or add it yourself by submitting a **pull request** that adds it to:
* `README.md`
* `pyproject.toml`
* `src/teachbooks_favourites/__init__.py`
- `README.md`
- `pyproject.toml`
- `src/teachbooks_favourites/__init__.py`
```{note}
Extensions must be stable, open-source, and enhance the TeachBooks authoring or learning experience.
```
7. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
8. Add a commit message.
9. To see your changes, go to {octicon}`play` **Actions** → select the most recent workflow run → wait for it to finish → click the link under *Branches deployed* and *Primary book at root*.
10. Don’t see your change? Press `CTRL+F5` / `Control+F5` to refresh the page.
```{note}
Extensions must be stable, open-source, and enhance the TeachBooks authoring or learning experience.
```
```{admonition} Check your understanding
:class: note