pydata_sphinx_theme.utils#
General helpers for the management of config parameters.
Attributes#
Functions#
|
Get the matching sidebar templates to render for the given pagename. |
|
Check whether the pattern contains a wildcard. |
|
Update templates to include html suffix if needed; remove templates which render empty. |
|
Check if the user has manually provided the config. |
|
Helper function to remove ansi coloring from sphinx warnings. |
Return theme options for the application w/ a fallback if they don't exist. |
|
|
Wraps the Sphinx logger to allow warning suppression. |
|
Set the secondary sidebar items to render for the given pagename. |
|
Triage node.traverse (docutils <0.18.1) vs node.findall. |
Module Contents#
- pydata_sphinx_theme.utils._get_matching_sidebar_items(pagename, sidebars)[source]#
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)[source]#
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)[source]#
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
orhtml_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 forpydata_sphinx_theme.update_and_remove_templates()
andpydata_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)[source]#
Check if the user has manually provided the config.
- Parameters:
key (str)
- Return type:
bool
- pydata_sphinx_theme.utils.escape_ansi(string)[source]#
Helper function to remove ansi coloring from sphinx warnings.
- Parameters:
string (str)
- Return type:
str
- pydata_sphinx_theme.utils.get_theme_options_dict(app)[source]#
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 ofapp.config.html_theme_options
(containing user-configs from theirconf.py
); sometimes that copy never occurs though which is why we check both.- Parameters:
- Return type:
Dict[str, Any]
- pydata_sphinx_theme.utils.maybe_warn(app, msg, *args, **kwargs)[source]#
Wraps the Sphinx logger to allow warning suppression.
- Parameters:
- pydata_sphinx_theme.utils.set_secondary_sidebar_items(app, pagename, templatename, context, doctree)[source]#
Set the secondary sidebar items to render for the given pagename.
- Parameters:
pagename (str)
templatename (str)
- Return type:
None
- pydata_sphinx_theme.utils.traverse_or_findall(node, condition, **kwargs)[source]#
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 (Union[Callable, type])
- Return type:
Iterable[docutils.nodes.Node]