diff --git a/book/_toc.yml b/book/_toc.yml index 68c7a8f..03d85b8 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -34,6 +34,7 @@ parts: - 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 diff --git a/book/extension_exercises/017.md b/book/extension_exercises/017.md new file mode 100644 index 0000000..29b2341 --- /dev/null +++ b/book/extension_exercises/017.md @@ -0,0 +1,112 @@ +# 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 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. | + +```{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: + +```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. +``` + +## 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: + + * `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. + +```{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? +```