stouputils.applications.automatic_docs.sphinx.theming module#

Theme, syntax highlighting and stylesheet concerns of the generated documentation.

Pygments’ Python lexer is coarse: it only tags an identifier as Name.Function or Name.Class when a literal def or class introduces it, and emits a bare Name for every call, attribute, argument and variable. A palette designed for a finer grammar therefore paints most of the code in whichever colour it gave Name. That is why the styles below are picked so that Name keeps the foreground colour, leaving hues for the tokens the lexer genuinely recognises.

DEFAULT_LIGHT_STYLE: str = 'vscode-light-plus'[source]#

Pygments style for light mode, transcribed from VS Code so a snippet matches the reader’s editor.

DEFAULT_DARK_STYLE: str = 'vscode-dark-plus'[source]#

Pygments style for dark mode.

The theme’s own default, github-dark-high-contrast, paints Name in #DBB7FF. Since a Python page emits about a hundred bare Name tokens for each def, that turns whole snippets violet.

CUSTOM_CSS: str = '\n/* Custom CSS for Sphinx documentation */\n/* Reduce heading sizes */\nh1 { font-size: 2.0em !important; }\nh2 { font-size: 1.6em !important; }\nh3 { font-size: 1.4em !important; }\nh4 { font-size: 1.2em !important; }\nh5 { font-size: 1.0em !important; }\nh6 { font-size: 0.9em !important; }\n\n/* Gradient animation keyframes */\n@keyframes shine-slide {\n\t0% { background-position: -200% center; }\n\t100% { background-position: 200% center; }\n}\n\n/* Adjustments to abmonition */\n.admonition {\n\ttext-decoration: none;\n\tpadding: 1rem;\n\tdisplay: block;\n}\n\n/* On hover animation for various elements */\na, h1, h2, h3, h4, h5, h6, .admonition {\n\ttransition: transform 0.3s;\n}\n\na:hover, h1:hover, h2:hover, h3:hover, h4:hover, h5:hover, h6:hover, .admonition:hover {\n\ttransform: scale(1.05);\n}\na:hover, a:hover span {\n\tbackground: linear-gradient(\n\t\t110deg,\n\t\tcurrentColor 0%,\n\t\tcurrentColor 40%,\n\t\twhite 50%,\n\t\tcurrentColor 60%,\n\t\tcurrentColor 100%\n\t);\n\tbackground-size: 200% 100%;\n\tbackground-clip: text;\n\t-webkit-background-clip: text;\n\t-webkit-text-fill-color: transparent;\n\tanimation: shine-slide 3.5s linear infinite;\n}\n\n/* A doctest prompt is a marker, not code, so it should never end up in what a reader copies by hand */\n.highlight .gp { user-select: none; }\n'[source]#

Stylesheet written to _static/custom.css and loaded on top of the theme.

check_dependencies(html_theme: str) → None[source]#

Check that the requested theme, and every base requirement, is installed.

Parameters:

html_theme (str) – HTML theme used by the documentation, ex: “breeze”, “pydata_sphinx_theme”, “furo”

Raises:

ImportError – If the theme or any base requirement is missing

get_theme_options(
html_theme: str,
default_mode: str,
) → dict[str, str | bool][source]#

Build the html_theme_options mapping, holding only keys the chosen theme understands.

default_mode reaches breeze through html_theme_options, and pydata through html_context. Passing it to a theme that knows neither only earns an “unsupported theme option” warning, so it is filtered here.

Parameters:

  • html_theme (str) – HTML theme used by the documentation

  • default_mode (str) – Colour mode a first-time visitor gets, one of “auto”, “light” or “dark”

Returns:

Options to write into the generated conf.py

Return type:

dict[str, str | bool]

Examples

>>> get_theme_options("breeze", "dark")
{'navigation_with_keys': True, 'default_mode': 'dark'}
>>> get_theme_options("furo", "dark")
{'navigation_with_keys': True}
write_custom_css(static_dir: str) → None[source]#

Write CUSTOM_CSS into the static folder the generated conf.py points at.

Parameters:

static_dir (str) – The docs/source/_static folder