TeachBooks Favourites

A collection of our favourite Sphinx extensions for use in JupyterBooks.

Introduction

This Sphinx extension provides a single extension that includes and activates our favourite Sphinx extensions for use in JupyterBooks:

• Sphinx-Thebe from TeachBooks:
  • Enabled live code in your browser
  • Manual: https://teachbooks.io/manual/features/live_code.html
• Jupyterbook patches:
  • Various patches by TeachBooks
  • Repository: https://github.com/TeachBooks/JupyterBook-Patches
  • Manual: https://teachbooks.io/manual/external/JupyterBook-Patches/README.html
• Download link replacer:
  • Allows you to replace and add downloadable files to a page header
  • Repository: https://github.com/TeachBooks/Download-Link-Replacer
  • Manual: https://teachbooks.io/manual/external/Download-Link-Replacer/README.html
• Sphinx image inverter
  • Inverts images for dark mode
  • Repository: https://github.com/TeachBooks/sphinx-image-inverter
  • Manual: https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html
• Sphinx iframes
  • Eases the embedding of iframes
  • Repository: https://github.com/TeachBooks/sphinx-iframes
  • Manual: https://teachbooks.io/manual/external/sphinx-iframes/README.html
• Sphinx exercise:
  • Allows you to add exercise admonitions to your book
  • Repository: https://github.com/executablebooks/sphinx-exercise
  • Manual: https://ebp-sphinx-exercise.readthedocs.io/en/latest/
• Teachbooks Sphinx tippy
  • Enables hover over tips
  • Repository: https://github.com/TeachBooks/teachbooks-sphinx-tippy
  • Manual: https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html
  • Remark: This is a fork of https://github.com/executablebooks/sphinx-tippy specifically adapted for TeachBooks
• Sphinx named colors
  • Allows you to use custom colors in your book
  • Repository: https://github.com/TeachBooks/sphinx-named-colors
  • Manual: https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html
• Sphinx dropdown toggle
  • Adds a button to toggle all dropdowns with one click
  • Repository: https://github.com/TeachBooks/sphinx-dropdown-toggle
  • Manual: https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-Dropdown-Toggle/main/MANUAL.html
• Sphinx proof:
  • Allows you to add various common math admonitions such as theorems to your book
  • Repository: https://github.com/executablebooks/sphinx-proof
  • Manual: https://sphinx-proof.readthedocs.io/en/latest/
• Sphinx code examples
  • Allows you to include code blocks and alternative visuals in examples
  • Repository: https://github.com/TeachBooks/sphinx-code-examples
  • Manual: https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html
• Sphinx accessibility
  • Allows dyslexic-friendly fonts and high contrast mode
  • Repository: https://github.com/TeachBooks/sphinx-accessibility
  • Manual: https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.html
• Sphinx toggle button
  • Allows you to add a toggle button to elements in your book
  • Repository: https://github.com/TeachBooks/sphinx-togglebutton
  • Manual: https://sphinx-togglebutton.readthedocs.io/en/latest/
  • Remark: Currently this is set to the TeachBooks fork, waiting for merge of executablebooks/sphinx-togglebutton#66
• NoteBook Execution Patterns
  • Allows include and exclude patterns for execution of notebooks during build
  • Repository: https://github.com/TeachBooks/Sphinx-NB-Execution-Patterns
  • Manual: https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html
• Sphinx Launch Buttons
  • Allows you to add a customizable button with links to the top right corner of your book
  • Repository: https://github.com/TeachBooks/manual
  • Manual: https://teachbooks.io/manual/external/Sphinx-launch-buttons/README.html
• Sphinx GitHub Alerts
  • Converts GitHub alerts to Sphinx admonitions.
  • Repository: https://github.com/TeachBooks/Sphinx-GitHub-Alerts
  • Manual: https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-GitHub-Alerts/main/README.html
• Spinx Metadata Figure
  • Provides an interface to add metadata to figures and display the metadata.
  • Repository: https://github.com/TeachBooks/Sphinx-Metadata-Figure
  • Manual: https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-Metadata-Figure/main/MANUAL.html
• Sphinx last updated by git
  • Allows a last updated note for every single page based on git history.
  • Repository + documentation: https://github.com/TeachBooks/sphinx-last-updated-by-git
  • Remark: Currently this is set to the TeachBooks fork, waiting for merge of mgeier/sphinx-last-updated-by-git#97
• Sphinx gated directives
  • Allows to used gated directives: more granular control over where the directive starts and ends and nesting directives more easily allowing nesting of code-celsl
  • Repository: https://github.com/TeachBooks/Sphinx-Gated-Directives
  • Manual: https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-Gated-Directives/main/MANUAL.html

The following extension is nice, but is not compatible with all setups (dependency clash) so is not included in TeachBooks-Favourites:

• Open in new tab
  • Allows you open links in a new tab
  • Repository: https://github.com/ftnext/sphinx-new-tab-link
  • Documentation: https://pypi.org/project/sphinx-new-tab-link/

The following extensions are included by default in your Jupyterbook distribution, but are included as dependencies to ensure you have the version of TeachBooks:

• Sphinx External ToC:
  • Allows you to define the Table of Contents external to the documentation files and set styling options per ToC-subtree.
  • Repository: https://github.com/TeachBooks/sphinx-external-toc
  • Manual: https://sphinx-external-toc.readthedocs.io/
  • Remark: Currently this is set to the TeachBooks fork, waiting for merge of executablebooks/sphinx-external-toc#112

Installation

To install TeachBooks-Favourites, follow these steps:

Step 1: Install the Package

Install the teachbooks-favourites package using pip:

pip install git+https://github.com/TeachBooks/TeachBooks-Favourites

Step 2: Add to requirements.txt

Make sure that the package is included in your project's requirements.txt to track the dependency:

git+https://github.com/TeachBooks/TeachBooks-Favourites

Step 3: Enable in _config.yml

In your _config.yml file, add the extension to the list of Sphinx extra extensions (important: underscore, not dash this time):

sphinx: 
    extra_extensions:
        - teachbooks_favourites

Usage

For using the various package we refer to the different manuals linked above.

All extensions are loaded with their default settings.

Contribute

Do you think we missed an extension that should really be included? Let us know by either

• creating a fork of this repository and submitting a pull request, in which you added the extension to the files
  • README.md
  • pyproject.toml
  • src\teachbooks_favourites\__init__.py
• opening an issue.