admin2/template
1
0
Fork 0
mirror of https://github.com/TeachBooks/template.git synced 2026-11-12 22:25: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

2
book/_toc.yml
View file

@ -31,10 +31,10 @@ parts:
- file: extensions.md
sections:
- file: exercises/007.md
- file: extension_exercises/017.md
- file: extension_exercises/014.md
- file: extension_exercises/015.md
- file: extension_exercises/016.md
- file: extension_exercises/017.md
- caption: Miscellaneous
chapters:
- file: references.md

89
book/extension_exercises/016.md
View file

@ -1,46 +1,16 @@
# Image and Iframe Dark Mode Colour Inverter
The **Sphinx-Image-Inverter** extension automatically adapts figures, images, and iframes to dark mode by inverting their colours. This ensures that visuals remain readable and consistent across light and dark themes. In this exercise, you’ll install the extension, configure its options, and experiment with enabling and disabling inversion for specific images.
The **Sphinx-Image-Inverter** extension automatically adapts figures, images, and iframes to dark mode by inverting their colours. Meanwhile, it makes sure that a colour is still recognizable, i.e. red stays red, blue stays blue, etc. This ensures that visuals remain readable and consistent across light and dark themes. In this exercise, you’ll install the extension, configure its options, and experiment with enabling and disabling inversion for specific images.
::::::{topic} Exercise objective
Can you configure the Sphinx-Image-Inverter to control how images and iframes behave in dark mode?
::::::
## Install and activate the extension
```{note}
If you cloned your book from the TeachBooks Template, this extension is already included and activated.
```
1. Install the package using `pip`:
```
pip install sphinx-image-inverter
```
2. Add the dependency to your `requirements.txt` file:
```
sphinx-image-inverter
```
3. Enable the extension in your `_config.yml` by ading it to the list of Sphinx extra extensions:
```yaml
sphinx:
extra_extensions:
- sphinx_image_inverter
```
4. Commit and rebuild your book — the extension is now active. By default, all images and figures will be inverted when dark mode is toggled.
## Configure image inversion
# Configure image inversion
You can control how and when images are inverted by adjusting parameters in `_config.yml`.
5. To disable inversion globally, set `inverter_all` to `false`. This disables automatic inversion for all images.
1. To disable inversion globally, set `inverter_all` to `false`. This disables automatic inversion for all images. This is especially useful if your images are photos which won't look good when inverted.
```yaml
sphinx:
@ -48,7 +18,7 @@ You can control how and when images are inverted by adjusting parameters in `_co
inverter_all: false
```
6. To enable inversion globally, set `inverter_all` to `true`. This enables automatic inversion for all images.
2. To enable inversion globally, set `inverter_all` to `true`. This enables automatic inversion for all images. This is useful if your images are mostly diagrams or plots which benefit from inversion.
```yaml
sphinx:
@ -56,22 +26,22 @@ You can control how and when images are inverted by adjusting parameters in `_co
inverter_all: true
```
7. If you would like to selectively include or exclude specific figures or iframes from inversion the `dark-light` class can be used. Locate the markdown file that contains the image you want to exclude from inversion and add the `:class: dark-light` attribute as follows:
3. If you would like to selectively include or exclude specific figures or iframes from inversion the `dark-light` class can be used. Locate the markdown file that contains the image you want to exclude from inversion and add the `:class: dark-light` attribute as follows:
````
```{figure} images/example_plot.png
:class: dark-light
:width: 400
```
````
````md
```{figure} images/example_plot.png
:class: dark-light
:width: 400
```
````
```{note}
When dark mode is toggled, this image will not be inverted if `inverter_all: true`.
If `inverter_all: false`, only this image will be inverted.
```
```{note}
When dark mode is toggled, this image will not be inverted if `inverter_all: true`.
If `inverter_all: false`, only this image will be inverted.
```
8. The saturation can also be adjusted. The default colour saturation is `1.5`. Let us reduce the contrast by changing this to `1.0`:
4. The saturation can also be adjusted. The default colour saturation is `1.5`. Let us reduce the contrast by changing this to `1.0`:
```yaml
sphinx:
@ -79,25 +49,25 @@ If `inverter_all: false`, only this image will be inverted.
inverter_saturation: 1.0
```
```{tip}
Try different saturation levels to see how they affect contrast in dark mode — between `1.0` (no change) and `2.0` (vivid colours) is recommended.
```
9. It is also possible to choose to show or hide text depending on the selected theme. This is useful for adding hints or notes that depend on visibility. Try this out using the following classes:
```{tip}
Try different saturation levels to see how they affect contrast in dark mode — between `1.0` (no change) and `2.0` (vivid colours) is recommended.
```
5. It is also possible to choose to show or hide text depending on the selected theme. This is useful for adding hints or notes that depend on visibility. Try this out using the following classes:
```html
<span class="only-light">This message is only visible in light mode.</span>
```html
<span class="only-light">This message is only visible in light mode.</span>
<span class="only-dark">This message appears only in dark mode.</span>
```
<span class="only-dark">This message appears only in dark mode.</span>
```
10. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
11. Add a commit message.
7. Add a commit message.
12. 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).
8. 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).
13. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
```{admonition} Check your understanding
@ -108,5 +78,4 @@ Before moving on, make sure you can answer:
- How do you disable automatic inversion for all images?
- What is the effect of the `dark-light` class?
- What happens when you change the `inverter_saturation` value?
```
```

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