Merge pull request #92 from TeachBooks/image_inverter

image inverter exercise

book/_toc.yml

@@ -31,8 +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
   - caption: Miscellaneous
     chapters:
     - file: references.md

book/extension_exercises/016.md

@@ -0,0 +1,80 @@
+# 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. 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?
+::::::
+
+# Configure image inversion
+
+You can control how and when images are inverted by adjusting parameters in `_config.yml`. 
+
+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:
+     config:
+       inverter_all: false
+   ```
+
+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:
+     config:
+       inverter_all: true
+   ```
+
+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:
+
+   ````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.
+   ```
+
+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:
+     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.
+   ```
+
+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>
+
+   <span class="only-dark">This message appears only in dark mode.</span>
+   ```
+
+6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
+
+7. Add a commit message.
+
+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).
+
+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
+: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?  
+```

book/extension_exercises/017.md

@@ -0,0 +1,64 @@
+# TeachBooks Favourites
+
+The **TeachBooks-Favourites** extension brings together TeachBooks’ most-used and most-loved features in one convenient package. It bundles several Sphinx extensions—developed both by TeachBooks and others—into a single install, making it easier to start a new TeachBook with all recommended functionality already enabled.
+
+This exercise will guide you through installing the **TeachBooks-Favourites** extension, enabling it in your configuration, and exploring what it includes.
+
+::::::{topic} Exercise objective
+Can you install and activate the TeachBooks-Favourites extension, and identify which tools it automatically enables?
+::::::
+
+## Explore what’s included
+
+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**.
+```
+
+## Customising your favourites
+
+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.
+
+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.
+    ```
+
+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
+
+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`
+
+    ```{note}
+    Extensions must be stable, open-source, and enhance the TeachBooks authoring or learning experience.
+    ```
+
+```{admonition} Check your understanding
+:class: note
+
+Before moving on, make sure you can answer:
+- What is the TeachBooks-Favourites extension?  
+- How do you enable it in `_config.yml`?  
+- What should you do if you only want to load a few of the extensions?  
+```