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, "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 set_secondary_sidebar_items(
    app: Sphinx, pagename: str, templatename: str, context, doctree
) -> None:
    """Set the secondary sidebar items to render for the given pagename."""
    if "theme_secondary_sidebar_items" in context:
        templates = context["theme_secondary_sidebar_items"]
        if isinstance(templates, dict):
            templates = _get_matching_sidebar_items(pagename, templates)

        context["secondary_sidebar_items"] = _update_and_remove_templates(
            app,
            context,
            templates,
            "theme_secondary_sidebar_items",
        )




[文档]
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 _get_matching_sidebar_items(
    pagename: str, sidebars: Dict[str, List[str]]
) -> List[str]:
    """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.
    """
    matched = None
    secondary_sidebar_items = []
    for pattern, sidebar_items in sidebars.items():
        if matching.patmatch(pagename, pattern):
            if matched and _has_wildcard(pattern) and _has_wildcard(matched):
                (
                    SPHINX_LOGGER.warning(
                        "Page %s matches two wildcard patterns in secondary_sidebar_items: %s and %s",  # noqa: E501
                        pagename,
                        matched,
                        pattern,
                    ),
                )
            matched = pattern
            secondary_sidebar_items = sidebar_items
    return secondary_sidebar_items




[文档]
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 "*?[")