Skip to main content
`Ctrl`+`K`

# Source code for pydata_sphinx_theme.utils

    """General helpers for the management of config parameters."""

    import copy
    import os
    import re

    from typing import Any, Callable, Dict, Iterable, List, Optional, Union

    from docutils.nodes import Node
    from sphinx.application import Sphinx
    from sphinx.util import logging, matching

    def get_theme_options_dict(app: Sphinx) -> Dict[str, Any]:
        """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.
        """
        if (
            hasattr(app, "builder")
            and app.builder is not None
            and hasattr(app.builder, "theme_options")
        ):
            return app.builder.theme_options
        elif hasattr(app.config, "html_theme_options"):
            return app.config.html_theme_options
        else:
            return {}

    def config_provided_by_user(app: Sphinx, key: str) -> bool:
        """Check if the user has manually provided the config."""
        return any(key in ii for ii in [app.config.overrides, app.config._raw_config])

    def traverse_or_findall(
        node: Node, condition: Union[Callable, type], **kwargs
    ) -> Iterable[Node]:
        """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.
        """
        return (
            node.findall(condition, **kwargs)
            if hasattr(node, "findall")
            else node.traverse(condition, **kwargs)
        )

    def escape_ansi(string: str) -> str:
        """Helper function to remove ansi coloring from sphinx warnings."""
        ansi_escape = re.compile(r"(\x9B|\x1B\[)[0-?]*[ -\/]*[@-~]")
        return ansi_escape.sub("", string)

    SPHINX_LOGGER = logging.getLogger(__name__)

    def maybe_warn(app: Sphinx, msg, *args, **kwargs):
        """Wraps the Sphinx logger to allow warning suppression."""
        theme_options = get_theme_options_dict(app)
        should_warn = theme_options.get("surface_warnings", False)
        if should_warn:
            SPHINX_LOGGER.warning(msg, *args, **kwargs)
        else:
            SPHINX_LOGGER.info(msg, *args, **kwargs)

    def _update_and_remove_templates(
        app: Sphinx,
        context: Dict[str, Any],
        templates: Union[List, str],
        section: str,
        templates_skip_empty_check: Optional[List[str]] = None,
    ) -> List[str]:
        """
        Update templates to include html suffix if needed; remove templates which render
        empty.

        Args:
            app: Sphinx application passed to the html page context
            context: The html page context; dictionary of values passed to the templating
                engine
            templates: A list of template names, or a string of comma separated template
                names
            section: 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
                :py:func:`pydata_sphinx_theme.update_and_remove_templates` and
                :py:func:`pydata_sphinx_theme.utils.set_secondary_sidebar_items`,
                both of which call this function.
            templates_skip_empty_check: 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
        """
        if templates_skip_empty_check is None:
            templates_skip_empty_check = []

        # Break apart `,` separated strings so we can use , in the defaults
        if isinstance(templates, str):
            templates = [template.strip() for template in templates.split(",")]

        # Add `.html` to templates with no suffix
        suffixed_templates = []
        for template in templates:
            if os.path.splitext(template)[1]:
                suffixed_templates.append(template)
            else:
                suffixed_templates.append(f"{template}.html")

        ctx = copy.copy(context)
        ctx.update({section: suffixed_templates})

        # Check whether the template renders to an empty string; remove if this is the case
        # Skip templates that are slow to render with templates_skip_empty_check
        filtered_templates = []
        for template in suffixed_templates:
            if any(template.endswith(item) for item in templates_skip_empty_check):
                filtered_templates.append(template)
            else:
                rendered = app.builder.templates.render(template, ctx)
                if len(rendered.strip()) != 0:
                    filtered_templates.append(template)

        return filtered_templates

    def _has_wildcard(pattern: str) -> bool:
        """Check whether the pattern contains a wildcard.

        Taken from sphinx.builders.StandaloneHTMLBuilder.add_sidebars.
        """
        return any(char in pattern for char in "*?[")