Sphinx extension: Named colors

Introduction

This extensions provides a simple solution to use CSS named colors and custom named colors in:

• $\LaTeX$;
• MarkDown text;
• Admonitions.

What does it do?

This extension defines, based on the CSS named color and custom named colors (provided by the user), several new

• $\LaTeX$ commands;
• Sphinx roles;
• Sphinx admonitions;
• Sphinx admonition classes;

that are styled by a generated CSS file.

If specified, each color will have a different value in the light and dark data-theme.

Installation

To use this extenstion, follow these steps:

Step 1: Install the Package

Install the sphinx-named-colors package using pip:

pip install sphinx-named-colors

Step 2: Add to requirements.txt

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

sphinx-named-colors

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_named_colors
        .
        .
        .

Configuration

This extension provides some configuration values, which can be added to:

sphinx: 
    config:
        .
        .
        .
        named_colors_include_CSS: true # default value
        named_colors_dark_and_light: true # default value
        named_colors_saturation: 1.5 # default value
        named_colors_custom_colors: None
        .
        .
        .

named_colors_include_CSS: true # default value

• If set to true all CSS named colors will be included in the extension.
• If set to false no CSS named colors will be included in the extension. If no custom named colors are defined, this extension will do nothing.

named_colors_dark_and_light: true # default value

• true: for all CSS named colors and all custom named colors a secondary value will be generated for use in the dark data-theme, unless otherwise specifed for custom colors. The generated colors emulate the same as the CSS filter invert(1) hue_rotate(180) saturate(<val>); where <val> is the value set by named_colors_saturation. This filter is also used in the Sphinx Image Inverter
• false: This disables the use of different colors in the dark data-theme, even if specified for custom colors.

named_colors_saturation: 1.5 # default value

• number: The saturation value used in the generation of the dark data-theme colors.

named_colors_custom_colors: None

• None: No custom named colors will be included.
• dictionary: A Python dictionary where each key defines a custom name and the value is a list of 3 or 6 integers, with each integer at minimum 0 and at maximum 255.
  • If 3 integers are provided, these are the RGB values of the custom named color and, if specified, the dark data-theme color will be generated.
  • If 6 integers are provided, the first set of 3 integers form the RGB values of the custom named color and the second set of 3 integers form the RGB values of the dark data-theme color.
  • Each key should contain only characters from the ranges a-z. Hyphens (-) are allowed, however this is not recommended.
  • An example value:
    • {'onlylight':[165,21,160],'lightanddark':[45,180,117,204,158,110]}

Provided code

$\LaTeX$ elements

Named colors without hyphens

\namedcolor{...}

• Only use in $\LaTeX$ code.
• This will typeset ... in the color namedcolor.

Named colors with hyphens

\class{namedcolor}{...}

• Only use in $\LaTeX$ code.
• This will typeset ... in the color namedcolor.

MarkDown elements

{namedcolor}`...`

• Only use in MarkDown code.
• This will typeset ... in the color namedcolor.

To provide the use of strong and/or emphasis colored text, we als provide the next three roles:

{namedcolor_strong}`...`

{namedcolor_emphasis}`...`

{namedcolor_strong_emphasis}`...`

These extra roles have been created using the extension sphinxnotes-comboroles.

Admonitions

Colored admonitions can be generated in two ways, explained below.

1. By adding a class to an existing admonition

::::{type} Title (optional or required, depending on type)
:class: namedcolor
Content
::::

2. By using a new admonition

::::{namedcolor} Title (optional)
Content
::::

If the title is omitted in the new admonition, the title bar will not be displayed.

In both cases extra classes can be added to the admonition to apply other styling.

A special new class for existing admonitions is also introduced: no-title. This suppresses printing of the title bar, even if the title is given. For the named color admonitions this happens automatically if no title is given.

For the named color admonitions the class show-bar is introduced for titleless admonitions. This forces printing of the title bar. If a title is given, the title will be printed too and adding the class show-bar is redundant.

You can define the symbol of your new admonition with the second method by defining it as:

::::{namedcolor} Title (optional)
:class: customsymbol
Content
::::

with a customsymbol.css-file in your _static-directory:

div.customsymbol > .admonition-title::after {
    content: "\<unicode_code_for_symbol>";
}

In which you replaces <unicode_code_for_symbol> with for example f10d to get a quotation symbol.

Examples & details

To see examples of usage visit this page in the TeachBooks manual.

Exercise

Check out this exercise in the TeachBooks template to see for yourself how to add colours to equations! Or this exercise to see how to make custom coloured admonitions

Contribute

This tool's repository is stored on GitHub. If you'd like to contribute, you can create a fork and open a pull request on the GitHub repository.

The README.md of the branch manual is also part of the TeachBooks manual as a submodule.