sphinx-tudelft-theme 1.1.0

A custom Sphinx extension to apply TU Delft styling to a TeachBook

Sphinx extension: TU Delft theme

Introduction

The default theme in JupyterBooks is usually not desired and need to be changed by adding custom stylesheets. The Sphinx-TUDelft-theme extension provides a simple solution to have a uniform theme across all the books created at Delft University of Technology that matches the TU Delft identity.

What does it do?

This extension applies styling changes, being

• particular colours (different colors for light and dark themes) for:
  • admonitions (e.g. hint, note, tip, error, etc.),
  • proofs (e.g. theorem, axiom, lemma, corollary, etc.),
  • exercises,
  • buttons,
  • badges,
  • custom components,
  • $\LaTeX$
• particular icons for:
  • proofs (e.g. theorem, axiom, lemma, corollary, etc.),
  • exercises,
  • custom components.

Unless specified otherwise, see Usage, this extension also automatically sets:

• a Delft University of Technology logo;
• a Delft University of Technology favicon;
• the Delft University of Technology preferred fonts;
• rendering text inside MathJax as the surrounding text;
• an always visible logo (i.e. a sticky logo).

You can see how the TU Delft theme looks like applied in this example book.

Installation

To implement the TU Delft theme, follow these steps:

Step 1: Install the Package

Install the sphinx-tudelft-theme package using pip:

pip install sphinx-tudelft-theme

Step 2: Add to requirements.txt

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

sphinx-tudelft-theme

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:
        - sphinx_tudelft_theme

Usage

By following the steps above, the theme will be applied automatically. To see the examples of usage visit the TeachBooks manual.

To use the defined colors inside $\LaTeX$ rendered with MathJax, one should use the command

\class{<color>}{<math>}

where <color> is one of the following colors:

• red
• blue
• green
• raspberry
• yellow
• darkGreen
• orange
• cyan
• gray
• purple
• pink
• darkBlue

and <math> is the $\LaTeX$ that should be rendered in the color <color>.

If a Delft University of Technology logo should not be set (i.e. use logos defined by the user), include the following in your _config.yml file:

sphinx:
  config:
    ...
    tud_change_logo: false

If a Delft University of Technology favicon should not be set (i.e. use a favicon defined by the user), include the following in your _config.yml file:

sphinx:
  config:
    ...
    tud_change_favicon: false

If the Delft University of Technology fonts should not be set (i.e. use fonts defined by the user), include the following in your _config.yml file:

sphinx:
  config:
    ...
    tud_change_fonts: false

If rendering text inside MathJax should not be the same as the surrounding html, include the following in your _config.yml file:

sphinx:
  config:
    ...
    tud_change_mtext: false

If a sticky logo is not preferred, include the following in your _config.yml file:

sphinx:
  config:
    ...
    tud_sticky_logo: false

Contribute

This tool's repository is stored on GitHub. The README.md of the branch Manual is also part of the TeachBooks manual as a submodule. If you'd like to contribute, you can create a fork and open a pull request on the GitHub repository. To update the README.md shown in the TeachBooks manual, create a fork and open a merge request for the GitHub repository of the manual. If you intent to clone the manual including its submodules, clone using: git clone [e-mail]:TeachBooks/manual.git.