TeachBooks Favourites

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.

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

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:

    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 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#

  1. Think an extension deserves a place among the favourites? You can contribute by opening an issue on GitHub, 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.

Check your understanding

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?

Contents