pydata_sphinx_theme.pygment

Handle pygment css.

inspired by the Furo theme pradyunsg/furo

Functions

_get_styles(formatter, prefix)	Get styles out of a formatter, where everything has the correct prefix.
get_pygments_stylesheet(light_style, dark_style)	Generate the theme-specific pygments.css.
get_theme_options_dict(app)	Return theme options for the application w/ a fallback if they don't exist.
maybe_warn(app, msg, *args, **kwargs)	Wraps the Sphinx logger to allow warning suppression.
overwrite_pygments_css(app[, exception])	Overwrite pygments.css to allow dynamic light/dark switching.

Module Contents

pydata_sphinx_theme.pygment._get_styles(formatter, prefix)

Get styles out of a formatter, where everything has the correct prefix.

Parameters:

• formatter (pygments.formatters.HtmlFormatter)

• prefix (str)

Return type:

None

pydata_sphinx_theme.pygment.get_pygments_stylesheet(light_style, dark_style)

Generate the theme-specific pygments.css.

There is no way to tell Sphinx how the theme handles modes.

Parameters:

• light_style (str)

• dark_style (str)

Return type:

str

pydata_sphinx_theme.pygment.get_theme_options_dict(app)

Return theme options for the application w/ a fallback if they don’t exist.

The “top-level” mapping (the one we should usually check first, and modify if desired) is app.builder.theme_options. It is created by Sphinx as a copy of app.config.html_theme_options (containing user-configs from their conf.py); sometimes that copy never occurs though which is why we check both.

Parameters:

app (sphinx.application.Sphinx)

Return type:

Dict[str, Any]

pydata_sphinx_theme.pygment.maybe_warn(app, msg, *args, **kwargs)

Wraps the Sphinx logger to allow warning suppression.

Parameters:

app (sphinx.application.Sphinx)

pydata_sphinx_theme.pygment.overwrite_pygments_css(app, exception=None)

Overwrite pygments.css to allow dynamic light/dark switching.

Sphinx natively supports config variables pygments_style and pygments_dark_style. However, quoting from www.sphinx-doc.org/en/master/development/theming.html#creating-themes

The pygments_dark_style setting […is used] when the CSS media query (prefers-color-scheme: dark) evaluates to true.

This does not allow for dynamic switching by the user, so at build time we overwrite the pygment.css file so that it embeds 2 versions:

• the light theme prefixed with “[data-theme=”light”]”

• the dark theme prefixed with “[data-theme=”dark”]”

Fallbacks are defined in this function in case the user-requested (or our theme-specified) pygments theme is not available.

Parameters:

app (sphinx.application.Sphinx)