pydata_sphinx_theme.utils

General helpers for the management of config parameters.

Module Contents

Functions

_get_matching_sidebar_items(pagename, sidebars)	Get the matching sidebar templates to render for the given pagename.
_has_wildcard(pattern)	Check whether the pattern contains a wildcard.
_update_and_remove_templates(app, context, templates, ...)	Update templates to include html suffix if needed; remove templates which render empty.
config_provided_by_user(app, key)	Check if the user has manually provided the config.
escape_ansi(string)	Helper function to remove ansi coloring from sphinx warnings.
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.
set_secondary_sidebar_items(app, pagename, ...)	Set the secondary sidebar items to render for the given pagename.
traverse_or_findall(node, condition, **kwargs)	Triage node.traverse (docutils <0.18.1) vs node.findall.

Attributes

SPHINX_LOGGER

pydata_sphinx_theme.utils._get_matching_sidebar_items(pagename, sidebars)

Get the matching sidebar templates to render for the given pagename.

If a page matches more than one pattern, a warning is emitted, and the templates for the last matching pattern are used.

This function was adapted from sphinx.builders.html.StandaloneHTMLBuilder.add_sidebars.

Parameters:

• pagename (str) –

• sidebars (Dict[str, List[str]]) –

Return type:

List[str]

pydata_sphinx_theme.utils._has_wildcard(pattern)

Check whether the pattern contains a wildcard.

Taken from sphinx.builders.StandaloneHTMLBuilder.add_sidebars.

Parameters:

pattern (str) –

Return type:

bool

pydata_sphinx_theme.utils._update_and_remove_templates(app, context, templates, section, templates_skip_empty_check=None)

Update templates to include html suffix if needed; remove templates which render empty.

Parameters:

• app (sphinx.application.Sphinx) – Sphinx application passed to the html page context

• context (Dict[str, Any]) – The html page context; dictionary of values passed to the templating engine

• templates (Union[List, str]) – A list of template names, or a string of comma separated template names

• section (str) – Name of the template section where the templates are to be rendered. Valid section names include any of the sphinx or html_theme_options that take templates or lists of templates as arguments, for example: theme_navbar_start, theme_primary_sidebar_end, theme_secondary_sidebar_items, sidebars, etc. For a complete list of valid section names, see the source for pydata_sphinx_theme.update_and_remove_templates() and pydata_sphinx_theme.utils.set_secondary_sidebar_items(), both of which call this function.

• templates_skip_empty_check (Optional[List[str]]) – Names of any templates which should never be removed from the list of filtered templates returned by this function. These templates aren’t checked if they render empty, which can save time if the template is slow to render.

Returns:

A list of template names (including ‘.html’ suffix) to render into the section

Return type:

List[str]

pydata_sphinx_theme.utils.config_provided_by_user(app, key)

Check if the user has manually provided the config.

Parameters:

• app (sphinx.application.Sphinx) –

• key (str) –

Return type:

bool

pydata_sphinx_theme.utils.escape_ansi(string)

Helper function to remove ansi coloring from sphinx warnings.

Parameters:

string (str) –

Return type:

str

pydata_sphinx_theme.utils.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.utils.maybe_warn(app, msg, *args, **kwargs)

Wraps the Sphinx logger to allow warning suppression.

Parameters:

app (sphinx.application.Sphinx) –

pydata_sphinx_theme.utils.set_secondary_sidebar_items(app, pagename, templatename, context, doctree)

Set the secondary sidebar items to render for the given pagename.

Parameters:

• app (sphinx.application.Sphinx) –

• pagename (str) –

• templatename (str) –

Return type:

None

pydata_sphinx_theme.utils.traverse_or_findall(node, condition, **kwargs)

Triage node.traverse (docutils <0.18.1) vs node.findall.

TODO: This check can be removed when the minimum supported docutils version for numpydoc is docutils>=0.18.1.

Parameters:

• node (docutils.nodes.Node) –

• condition (str) –

Return type:

Iterator[docutils.nodes.Node]

pydata_sphinx_theme.utils.SPHINX_LOGGER