mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-13 14:45:52 +00:00
112 lines
5.2 KiB
Markdown
112 lines
5.2 KiB
Markdown
# 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?
|
||
```
|