image inverter exercise

book/_toc.yml

@@ -33,6 +33,7 @@ parts:
       - file: exercises/007.md
       - file: extension_exercises/014.md
       - file: extension_exercises/015.md
+      - file: extension_exercises/016.md
   - caption: Miscellaneous
     chapters:
     - file: references.md

book/extension_exercises/016.md

@@ -0,0 +1,112 @@
+# 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.
+
+::::::{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
+
+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.  
+
+   ```yaml
+   sphinx:
+     config:
+       inverter_all: false
+   ```
+
+6. To enable inversion globally, set `inverter_all` to `true`. This enables automatic inversion for all images.  
+
+   ```yaml
+   sphinx:
+     config:
+       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:
+
+````
+```{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.
+```
+
+
+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`:
+
+   ```yaml
+   sphinx:
+     config:
+       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:
+
+
+```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>
+```
+
+10. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
+
+11. 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).
+
+13. 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 can answer:
+- What does the Sphinx-Image-Inverter extension do?  
+- 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?  
+```
+