custom_directives.py

import copy
import logging
import logging.handlers
import os
import pathlib
import random
import re
import subprocess
import urllib
import urllib.request
from collections import defaultdict
from collections.abc import Iterable
from enum import Enum
from functools import lru_cache
from queue import Queue
from typing import Any, Callable, Dict, List, Optional, Tuple, Union

import bs4
import requests
import sphinx
import yaml
from docutils import nodes
from pydata_sphinx_theme.toctree import add_collapse_checkboxes
from pygments import highlight
from pygments.formatters import HtmlFormatter
from pygments.lexers import PythonLexer
from sphinx.util import logging as sphinx_logging
from sphinx.util.console import red  # type: ignore
from sphinx.util.nodes import make_refnode

from preprocess_github_markdown import preprocess_github_markdown_file

import json
from packaging.version import Version

logger = logging.getLogger(__name__)

__all__ = [
    "DownloadAndPreprocessEcosystemDocs",
    "update_context",
    "LinkcheckSummarizer",
    "setup_context",
]

# Taken from https://github.com/edx/edx-documentation
FEEDBACK_FORM_FMT = (
    "https://github.com/ray-project/ray/issues/new?"
    "title={title}&labels=docs&body={body}"
)

EXAMPLE_GALLERY_CONFIGS = [
    "source/data/examples.yml",
    "source/serve/examples.yml",
    "source/train/examples.yml",
]

# Grab a list of all files tracked by git; this is used to determine
# what pages should show an "Edit on GitHub" link (autogenerated pages
# shouldn't show this link)
TRACKED_FILES = (
    subprocess.run(
        ["git", "ls-files", pathlib.Path(__file__).parent], capture_output=True
    )
    .stdout.decode("utf8")
    .strip()
    .split("\n")
)


def feedback_form_url(project, page):
    """Create a URL for feedback on a particular page in a project."""
    return FEEDBACK_FORM_FMT.format(
        title=urllib.parse.quote("[docs] Issue on `{page}.rst`".format(page=page)),
        body=urllib.parse.quote(
            "# Documentation Problem/Question/Comment\n"
            "<!-- Describe your issue/question/comment below. -->\n"
            "<!-- If there are typos or errors in the docs, feel free "
            "to create a pull-request. -->\n"
            "\n\n\n\n"
            "(Created directly from the docs)\n"
        ),
    )


def update_context(app, pagename, templatename, context, doctree):
    """Update the page rendering context to include ``feedback_form_url``."""
    context["feedback_form_url"] = feedback_form_url(app.config.project, pagename)


# Add doc files from external repositories to be downloaded during build here
# (repo, ref, path to get, path to save on disk)
EXTERNAL_MARKDOWN_FILES = []


class DownloadAndPreprocessEcosystemDocs:
    """
    This class downloads markdown readme files for various
    ecosystem libraries, saves them in specified locations and preprocesses
    them before sphinx build starts.

    If you have ecosystem libraries that live in a separate repo from Ray,
    adding them here will allow for their docs to be present in Ray docs
    without the need for duplicate files. For more details, see ``doc/README.md``.
    """

    def __init__(self, base_path: str) -> None:
        self.base_path = pathlib.Path(base_path).absolute()
        assert self.base_path.is_dir()
        self.original_docs = {}

    @staticmethod
    def get_latest_release_tag(repo: str) -> str:
        """repo is just the repo name, eg. ray-project/ray"""
        response = requests.get(f"https://api.github.com/repos/{repo}/releases/latest")
        return response.json()["tag_name"]

    @staticmethod
    def get_file_from_github(
        repo: str, ref: str, path_to_get_from_repo: str, path_to_save_on_disk: str
    ) -> None:
        """If ``ref == "latest"``, use latest release"""
        if ref == "latest":
            ref = DownloadAndPreprocessEcosystemDocs.get_latest_release_tag(repo)
        urllib.request.urlretrieve(
            f"https://raw.githubusercontent.com/{repo}/{ref}/{path_to_get_from_repo}",
            path_to_save_on_disk,
        )

    def save_original_doc(self, path: str):
        with open(path, "r") as f:
            self.original_docs[path] = f.read()

    def write_new_docs(self, *args, **kwargs):
        for (
            repo,
            ref,
            path_to_get_from_repo,
            path_to_save_on_disk,
        ) in EXTERNAL_MARKDOWN_FILES:
            path_to_save_on_disk = self.base_path.joinpath(path_to_save_on_disk)
            self.save_original_doc(path_to_save_on_disk)
            self.get_file_from_github(
                repo, ref, path_to_get_from_repo, path_to_save_on_disk
            )
            preprocess_github_markdown_file(path_to_save_on_disk)

    def write_original_docs(self, *args, **kwargs):
        for path, content in self.original_docs.items():
            with open(path, "w") as f:
                f.write(content)

    def __call__(self):
        self.write_new_docs()


class _BrokenLinksQueue(Queue):
    """Queue that discards messages about non-broken links."""

    def __init__(self, maxsize: int = 0) -> None:
        self._last_line_no = None
        self.used = False
        super().__init__(maxsize)

    def put(self, item: logging.LogRecord, block=True, timeout=None):
        self.used = True
        message = item.getMessage()
        # line nos are separate records
        if ": line" in message:
            self._last_line_no = item
        # same formatting as in sphinx.builders.linkcheck
        # to avoid false positives if "broken" is in url
        if red("broken    ") in message or "broken link:" in message:
            if self._last_line_no:
                super().put(self._last_line_no, block=block, timeout=timeout)
                self._last_line_no = None
            return super().put(item, block=block, timeout=timeout)


class _QueueHandler(logging.handlers.QueueHandler):
    """QueueHandler without modifying the record."""

    def prepare(self, record: logging.LogRecord) -> logging.LogRecord:
        return record


class LinkcheckSummarizer:
    """Hook into the logger used by linkcheck to display a summary at the end."""

    def __init__(self) -> None:
        self.logger = None
        self.queue_handler = None
        self.log_queue = _BrokenLinksQueue()

    def add_handler_to_linkcheck(self, *args, **kwargs):
        """Adds a handler to the linkcheck logger."""
        self.logger = sphinx_logging.getLogger("sphinx.builders.linkcheck")
        self.queue_handler = _QueueHandler(self.log_queue)
        if not self.logger.hasHandlers():
            # If there are no handlers, add the one that would
            # be used anyway.
            self.logger.logger.addHandler(logging.lastResort)
        self.logger.logger.addHandler(self.queue_handler)

    def summarize(self, *args, **kwargs):
        """Summarizes broken links."""
        if not self.log_queue.used:
            return

        self.logger.logger.removeHandler(self.queue_handler)

        self.logger.info("\nBROKEN LINKS SUMMARY:\n")
        has_broken_links = False
        while self.log_queue.qsize() > 0:
            has_broken_links = True
            record: logging.LogRecord = self.log_queue.get()
            self.logger.handle(record)

        if not has_broken_links:
            self.logger.info("No broken links found!")


def parse_navbar_config(app: sphinx.application.Sphinx, config: sphinx.config.Config):
    """Parse the navbar config file into a set of links to show in the navbar.

    Parameters
    ----------
    app : sphinx.application.Sphinx
        Application instance passed when the `config-inited` event is emitted
    config : sphinx.config.Config
        Initialized configuration to be modified
    """
    if "navbar_content_path" in config:
        filename = app.config["navbar_content_path"]
    else:
        filename = ""

    if filename:
        with open(pathlib.Path(__file__).parent / filename, "r") as f:
            config.navbar_content = yaml.safe_load(f)
    else:
        config.navbar_content = None


NavEntry = Dict[str, Union[str, List["NavEntry"]]]


def preload_sidebar_nav(
    get_toctree: Callable[[Any], str],
    pathto: Callable[[str], str],
    root_doc: str,
    pagename: str,
) -> bs4.BeautifulSoup:
    """Return the navigation link structure in HTML.

    This function is modified from the pydata_sphinx_theme function
    `generate_toctree_html`. However, for ray we only produce one
    sidebar for all pages. We therefore can call this function just once (per worker),
    cache the result, and reuse it.

    The result of this function is equivalent to calling

        pydata_sphinx_theme.toctree.generate_toctree_html(
            "sidebar",
            startdepth=0,
            show_nav_level=0,
            collapse=False,
            includehidden=True,
            maxdepth=4,
            titles_only=True
        )

    Here we cache the result on this function itself because the `get_toctree`
    function is not the same instance for each `html-page-context` event, even
    if the toctree content is identical.

    Parameters
    ----------
    get_toctree : Callable[[Any], str]
        The function defined in context["toctree"] when html-page-context is triggered

    Returns
    -------
    bs4.BeautifulSoup
        Soup to display in the side navbar
    """
    if hasattr(preload_sidebar_nav, "cached_toctree"):
        # Need to retrieve a copy of the cached toctree HTML so as not to modify
        # the cached version when we set the "checked" state of the inputs
        soup = copy.copy(preload_sidebar_nav.cached_toctree)
    else:
        toctree = get_toctree(
            collapse=False, includehidden=True, maxdepth=4, titles_only=True
        )

        soup = bs4.BeautifulSoup(toctree, "html.parser")

        # Remove "current" class since this toctree HTML is being reused
        # from some other page
        for li in soup("li", {"class": "current"}):
            li["class"].remove("current")

        # Remove sidebar links to sub-headers on the page
        for li in soup.select("li"):
            # Remove
            if li.find("a"):
                href = li.find("a")["href"]
                if "#" in href and href != "#":
                    li.decompose()

        # Add bootstrap classes for first `ul` items
        for ul in soup("ul", recursive=False):
            ul.attrs["class"] = ul.attrs.get("class", []) + ["nav", "bd-sidenav"]

        # Add collapse boxes for parts/captions.
        # Wraps the TOC part in an extra <ul> to behave like chapters with toggles
        # show_nav_level: 0 means make parts collapsible.
        partcaptions = soup.find_all("p", attrs={"class": "caption"})
        if len(partcaptions):
            new_soup = bs4.BeautifulSoup(
                "<ul class='list-caption'></ul>", "html.parser"
            )
            for caption in partcaptions:
                # Assume that the next <ul> element is the TOC list
                # for this part
                for sibling in caption.next_siblings:
                    if sibling.name == "ul":
                        toclist = sibling
                        break
                li = soup.new_tag("li", attrs={"class": "toctree-l0"})
                li.extend([caption, toclist])
                new_soup.ul.append(li)
            soup = new_soup

        # Add icons and labels for collapsible nested sections
        add_collapse_checkboxes(soup)

        # Cache a fresh copy of the toctree HTML
        preload_sidebar_nav.cached_toctree = copy.copy(soup)

    # All the URIs are relative to the current document location, e.g.
    # "../../<whatever.html>". There's no need for this, and it messes up the build if
    # we reuse the same sidebar (with different relative URIs for various pages) on
    # different pages. Replace the leading "../" sequences in the hrefs with the correct
    # number of "../" for the given rootdoc
    if pagename == root_doc:
        to_root_prefix = "./"
    else:
        to_root_prefix = re.sub(f"{root_doc}.html", "", pathto(root_doc))

    for a in soup.select("a"):
        absolute_href = re.sub(r"^(\.\.\/)*", "", a["href"])
        a["href"] = to_root_prefix + absolute_href

        if absolute_href == f"{pagename}.html":

            # Add a current-page class to the parent li element for styling
            parent_li = a.find_parent("li")
            parent_li["class"] = parent_li.get("class", []) + ["current-page"]

            # Open the dropdowns of every parent li for the active page
            for parent_li in a.find_parents("li", attrs={"class": "has-children"}):
                el = parent_li.find("input")
                if el:
                    el.attrs["checked"] = True

    return soup


class ExampleEnum(Enum):
    """Enum which allows easier enumeration of members for example metadata."""

    @classmethod
    def items(cls: type) -> Iterable[Tuple["ExampleEnum", str]]:
        """Return an iterable mapping between the enum type and the corresponding value.

        Returns
        -------
        Dict['ExampleEnum', str]
            Dictionary of enum type, enum value for the enum class
        """
        yield from {entry: entry.value for entry in cls}.items()

    @classmethod
    def values(cls: type) -> List[str]:
        """Return a list of the values of the enum.

        Returns
        -------
        List[str]
            List of values for the enum class
        """
        return [entry.value for entry in cls]

    @classmethod
    def _missing_(cls: type, value: str) -> "ExampleEnum":
        """Allow case-insensitive lookup of enum values.

        This shouldn't be called directly. Instead this is called when e.g.,
        "SkillLevel('beginner')" is called.

        Parameters
        ----------
        value : str
            Value for which the associated enum class instance is to be returned.
            Spaces are stripped from the beginning and end of the string, and
            matching is case-insensitive.

        Returns
        -------
        ExampleEnum
            Enum class instance for the requested value
        """
        value = value.lstrip().rstrip().lower()
        for member in cls:
            if member.value.lstrip().rstrip().lower() == value:
                return member
        return None

    @classmethod
    def formatted_name(cls: type) -> str:
        """Return the formatted name for the class."""
        raise NotImplementedError

    @classmethod
    def key(cls: type) -> str:
        raise NotImplementedError


class Contributor(ExampleEnum):
    RAY_TEAM = "Maintained by the Ray Team"
    COMMUNITY = "Contributed by the Ray Community"

    @property
    def tag(self):
        if self == Contributor.RAY_TEAM:
            return "ray-team"
        return "community"

    @classmethod
    def formatted_name(cls):
        return "All Examples"

    @classmethod
    def key(cls: type) -> str:
        return "contributor"


class UseCase(ExampleEnum):
    """Use case type for example metadata."""

    LARGE_LANGUAGE_MODELS = "Large Language Models"
    GENERATIVE_AI = "Generative AI"
    COMPUTER_VISION = "Computer Vision"
    NATURAL_LANGUAGE_PROCESSING = "Natural Language Processing"

    @classmethod
    def formatted_name(cls):
        return "Use Case"

    @classmethod
    def key(cls: type) -> str:
        return "use_case"


class SkillLevel(ExampleEnum):
    """Skill level type for example metadata."""

    BEGINNER = "Beginner"
    INTERMEDIATE = "Intermediate"
    ADVANCED = "Advanced"

    @classmethod
    def formatted_name(cls):
        return "Skill Level"

    @classmethod
    def key(cls: type) -> str:
        return "skill_level"


class Framework(ExampleEnum):
    """Framework type for example metadata."""

    AWSNEURON = "AWS Neuron"
    PYTORCH = "PyTorch"
    LIGHTNING = "Lightning"
    TRANSFORMERS = "Transformers"
    ACCELERATE = "Accelerate"
    DEEPSPEED = "DeepSpeed"
    TENSORFLOW = "TensorFlow"
    HOROVOD = "Horovod"
    XGBOOST = "XGBoost"
    HUGGINGFACE = "Hugging Face"
    DATAJUICER = "Data-Juicer"
    VLLM = "vLLM"
    ANY = "Any"

    @classmethod
    def formatted_name(cls):
        return "Framework"

    @classmethod
    def key(cls: type) -> str:
        return "framework"


class RelatedTechnology(ExampleEnum):
    ML_APPLICATIONS = "ML Applications"
    INTEGRATIONS = "Integrations"
    AI_ACCELERATORS = "AI Accelerators"

    @classmethod
    def formatted_name(cls):
        return "Related Technology"

    @classmethod
    def key(cls: type) -> str:
        return "related_technology"


class Library(ExampleEnum):
    """Library type for example metadata."""

    DATA = "Data"
    SERVE = "Serve"
    TRAIN = "Train"

    @classmethod
    def formatted_name(cls):
        return "Library"

    @classmethod
    def key(cls: type) -> str:
        return "library"

    @classmethod
    def from_path(cls, path: Union[pathlib.Path, str]) -> "Library":
        """Instantiate a Library instance from a path.

        This function works its way up the file tree until it finds a directory that
        matches one of the enum types; if none is found, raise an exception.

        Parameters
        ----------
        path : Union[pathlib.Path, str]
            Path containing a directory named the same as one of the enum types.

        Returns
        -------
        Library
            A new Library instance for the given path.
        """
        if isinstance(path, str):
            path = pathlib.Path(path)

        for part in path.parts:
            try:
                return Library(part)
            except ValueError:
                continue

        raise ValueError(f"Cannot find library name from example config path {path}")


class Example:
    """Class containing metadata about an example to be shown in the example gallery."""

    def __init__(
        self, config: Dict[str, str], library: Library, config_dir: pathlib.Path
    ):
        self.config_dir = config_dir
        self.library = library

        self.frameworks = []
        for framework in config.get("frameworks", []):
            self.frameworks.append(Framework(framework.strip()))

        self.use_cases = []
        for use_case in config.get("use_cases", []):
            self.use_cases.append(UseCase(use_case.strip()))

        contributor = config.get("contributor", "").strip()
        if contributor:
            if contributor == "community":
                self.contributor = Contributor.COMMUNITY
            elif contributor == "ray team":
                self.contributor = Contributor.RAY_TEAM
            else:
                raise ValueError(
                    f"Invalid contributor type specified: {contributor}. Must be "
                    " either 'ray team' or 'community'."
                )
        else:
            self.contributor = Contributor.RAY_TEAM

        related_technology = config.get("related_technology", "").strip()
        if related_technology:
            self.related_technology = RelatedTechnology(related_technology)
        self.skill_level = SkillLevel(config.get("skill_level"))
        self.title = config.get("title")

        if "link" not in config:
            raise ValueError(
                "All examples must provide a link to either an external resource "
                "(starting with http://...) or a relative path to an internal page "
                "that is part of the Ray docs."
            )

        link = config["link"]
        if link.startswith("http"):
            self.link = link
        else:
            self.link = str(config_dir / link)

        if self.title is None:
            raise ValueError(f"Title of an example {config} must be set.")

        if self.link is None:
            raise ValueError(
                f"An internal or external link must be specified: {config}"
            )


class ExampleConfig:
    """Object which holds configuration data for a set of library examples."""

    def __init__(
        self, path: Union[pathlib.Path, str], src_dir: Union[pathlib.Path, str]
    ):
        """Parse a config file containing examples to display in the example gallery.

        Parameters
        ----------
        path : Union[pathlib.Path, str]
            Path to the `examples.yml` to be parsed
        root_dir : Union[pathlib.Path, str]
            Path to the root of the docs directory; `app.srcdir`
        """
        if isinstance(path, str):
            path = pathlib.Path(path)

        if not path.exists():
            raise ValueError(f"No configuration file found at {path}.")

        with open(path, "r") as f:
            config = yaml.safe_load(f)

        self.config_path = path
        self.library = Library.from_path(path)
        self.examples = self.parse_examples(config.get("examples", []), src_dir)
        self.text = config.get("text", "")
        self.columns_to_show = self.parse_columns_to_show(
            config.get("columns_to_show", [])
        )
        groupby = config.get("groupby", "skill_level")
        for cls in ExampleEnum.__subclasses__():
            if cls.key() == groupby:
                self.groupby = cls
                break
        else:
            valid_classes = [cls.key() for cls in ExampleEnum.__subclasses__()]
            raise ValueError(
                f"Unable to find class to group example entries by {groupby}. "
                f"Valid choices are {valid_classes}.",
            )

    def parse_columns_to_show(self, columns: str) -> Dict[str, type]:
        """Parse the columns to show in the library example page for the config.

        Note that a link to the example is always shown, and cannot be hidden.

        Parameters
        ----------
        columns : str
            Column names to show; valid names are any subclass of ExampleEnum, e.g.
            UseCase, Framework, etc.

        Returns
        -------
        List[type]
            A list of the ExampleEnum classes for which columns are to be shown
        """
        cols = {}
        for col in columns:
            if col == "use_cases":
                cols["use_cases"] = UseCase
            elif col == "frameworks":
                cols["frameworks"] = Framework
            else:
                raise ValueError(
                    f"Invalid column name {col} specified in {self.config_path}"
                )
        return cols

    def parse_examples(
        self, example_config: List[Dict[str, str]], src_dir: Union[pathlib.Path, str]
    ) -> List[Example]:
        """Parse the examples in the given configuration.

        Raise an exception if duplicate examples are found in the configuration file.

        Parameters
        ----------
        path : pathlib.Path
            Path to the example file to parse

        Returns
        -------
        List[Example]
            List of examples from the parsed configuration file
        """
        links = set()
        examples = []
        for entry in example_config:
            example = Example(
                entry, self.library, self.config_path.relative_to(src_dir).parent
            )
            if example.link in links:
                raise ValueError(
                    f"A duplicate example {example.link} was specified in "
                    f"{self.config_path}. Please remove duplicates and rebuild."
                )
            links.add(example.link)
            examples.append(example)

        return examples

    def __iter__(self):
        yield from self.examples


def setup_context(app, pagename, templatename, context, doctree):
    def render_library_examples(config: pathlib.Path = None) -> bs4.BeautifulSoup:
        """Render a table of links to examples for a given Ray library.

        Duplicate examples will result in an error.

        Parameters
        ----------
        config : pathlib.Path
            Path to the examples.yml file for the Ray library

        Returns
        -------
        bs4.BeautifulSoup
            Table of links to examples for the library, rendered as HTML
        """
        if config is None:
            config = (pathlib.Path(app.confdir) / pagename).parent / "examples.yml"

        # Keep track of whether any of the examples have frameworks metadata; the
        # column will not be shown if no frameworks metadata exists on any example.

        # Group the examples by the ExampleConfig.groupby value:
        examples = defaultdict(list)
        example_config = ExampleConfig(config, app.srcdir)
        for example in example_config:
            try:
                group = getattr(example, example_config.groupby.key())
            except AttributeError as e:
                raise AttributeError(
                    f"Example {example.link} has no {example_config.groupby.key()} "
                    "key, but needs one because the examples for library "
                    f"{example_config.library.value} are configured to be grouped "
                    f"by {example_config.groupby.key()}."
                ) from e
            examples[group].append(example)

        # Construct a table of examples
        soup = bs4.BeautifulSoup()

        # Add the main heading to the page and include the page text
        page_title = soup.new_tag("h1")
        page_title.append(f"{example_config.library.value} Examples")
        soup.append(page_title)

        page_text = soup.new_tag("p")
        page_text.append(example_config.text)
        soup.append(page_text)

        container = soup.new_tag("div", attrs={"class": "example-index"})
        for group, group_examples in examples.items():
            if not group_examples:
                continue

            header = soup.new_tag("h2", attrs={"class": "example-header"})
            header.append(group.value)
            container.append(header)

            table = soup.new_tag("table", attrs={"class": ["table", "example-table"]})

            # If there are additional columns to show besides just the example link,
            # include column titles in the table header
            if len(example_config.columns_to_show) > 0:
                thead = soup.new_tag("thead")
                thead_row = soup.new_tag("tr")

                for example_enum in example_config.columns_to_show.values():
                    col_header = soup.new_tag("th")
                    col_label = soup.new_tag("p")
                    col_label.append(example_enum.formatted_name())

                    col_header.append(col_label)
                    thead_row.append(col_header)

                link_col = soup.new_tag("th")
                link_label = soup.new_tag("p")
                link_label.append("Example")
                link_col.append(link_label)
                thead_row.append(link_col)

                thead.append(thead_row)
                table.append(thead)

            tbody = soup.new_tag("tbody")
            for example in group_examples:
                tr = soup.new_tag("tr")

                # The columns specify which attributes of each example to show;
                # for each attribute, a new cell value is added with the attribute from
                # the example
                if len(example_config.columns_to_show) > 0:
                    for attribute in example_config.columns_to_show:
                        col_td = soup.new_tag("td")
                        col_p = soup.new_tag("p")

                        attribute_value = getattr(example, attribute, "")
                        if isinstance(attribute_value, str):
                            col_p.append(attribute_value)
                        elif isinstance(attribute_value, list):
                            col_p.append(
                                ", ".join(item.value for item in attribute_value)
                            )

                        col_td.append(col_p)
                        tr.append(col_td)

                link_td = soup.new_tag("td")
                link_p = soup.new_tag("p")
                if example.link.startswith("http"):
                    link_href = soup.new_tag("a", attrs={"href": example.link})
                else:
                    link_href = soup.new_tag(
                        "a", attrs={"href": context["pathto"](example.link)}
                    )
                link_span = soup.new_tag("span")
                link_span.append(example.title)
                link_href.append(link_span)
                link_p.append(link_href)
                link_td.append(link_p)
                tr.append(link_td)
                tbody.append(tr)

            table.append(tbody)
            container.append(table)

        soup.append(container)
        return soup

    def render_example_gallery(configs: Iterable[pathlib.Path] = None) -> str:
        """Load and render examples for the example gallery.

        This function grabs examples from the various example gallery indexes.
        Each Ray library team maintains its own yml file which a standardized
        set of metadata with each example to ensure consistency across the
        code base.

        Duplicate examples will not raise an error as long as their fields match
        exactly.

        Parameters
        ----------
        configs : Iterable[pathlib.Path]
            Paths to example gallery files to ingest

        Returns
        -------
        str
            Example gallery examples rendered as HTML
        """
        if configs is None:
            configs = EXAMPLE_GALLERY_CONFIGS

        examples = {}
        for config in configs:
            config_path = pathlib.Path(config).relative_to("source")
            example_config = ExampleConfig(
                pathlib.Path(app.confdir) / config_path, app.srcdir
            )
            for example in example_config:
                # Check the ingested examples for duplicates. If there are duplicates,
                # check that they have the same field values, and keep only one.
                if example.link in examples:
                    existing_example_fields = vars(examples[example.link])
                    for key, value in vars(example):
                        if existing_example_fields.get(key) != value:
                            raise ValueError(
                                "One example was specified twice with different "
                                f"attributes: {vars(example)}\n"
                                f"{existing_example_fields}"
                            )
                else:
                    examples[example.link] = example

        soup = bs4.BeautifulSoup()
        list_area = soup.new_tag("div", attrs={"class": ["example-list-area"]})
        for example in examples.values():
            example_div = soup.new_tag("div", attrs={"class": "example"})

            if example.link.startswith("http"):
                link = example.link
            else:
                link = context["pathto"](example.link)

            example_link = soup.new_tag(
                "a",
                attrs={
                    "class": "example-link",
                    "href": link,
                },
            )
            example_icon_area = soup.new_tag(
                "div", attrs={"class": "example-icon-area"}
            )
            icon = soup.new_tag(
                "img",
                attrs={
                    "class": "example-icon",
                    "src": f"../_static/img/icon_bg_{random.randint(1, 5)}.jpg",
                },
            )
            remix_icon = soup.new_tag(
                "i", attrs={"class": f"{random.choice(REMIX_ICONS)} remix-icon"}
            )
            icon.append(remix_icon)
            example_icon_area.append(icon)
            example_link.append(example_icon_area)

            example_text_area = soup.new_tag(
                "div", attrs={"class": "example-text-area"}
            )

            example_title = soup.new_tag("b", attrs={"class": "example-title"})
            example_title.append(example.title)
            example_text_area.append(example_title)

            example_tags = soup.new_tag("span", attrs={"class": "example-tags"})
            frameworks = [item.value for item in example.frameworks]
            example_tags.append(
                ". ".join(
                    [example.skill_level.value, example.library.value, *frameworks]
                )
                + "."
            )
            example_text_area.append(example_tags)

            other_keywords = soup.new_tag(
                "span", attrs={"class": "example-other-keywords"}
            )
            other_keywords.append(
                " ".join(use_case.value for use_case in example.use_cases)
            )
            other_keywords.append(f" {example.contributor.tag}")
            example_text_area.append(other_keywords)

            # Add the appropriate text if the example comes from the community
            if example.contributor == Contributor.COMMUNITY:
                community_text_area = soup.new_tag(
                    "div", attrs={"class": "community-text-area"}
                )
                community_text = soup.new_tag("i", attrs={"class": "community-text"})
                community_text.append("*Contributed by the Ray Community")
                community_text_area.append(community_text)

                # Add emojis separately; they're not italicized in the mockups
                emojis = soup.new_tag("span", attrs={"class": "community-emojis"})
                emojis.append("💪 ✨")
                community_text_area.append(emojis)
                example_text_area.append(community_text_area)

            example_link.append(example_text_area)
            example_div.append(example_link)
            list_area.append(example_div)

        soup.append(list_area)
        return soup

    @lru_cache(maxsize=None)
    def render_header_nav_links() -> bs4.BeautifulSoup:
        """Render external header links into the top nav bar.
        The structure rendered here is defined in an external yaml file.

        Returns
        -------
        str
            Raw HTML to be rendered in the top nav bar
        """
        if not hasattr(app.config, "navbar_content"):
            raise ValueError(
                "A template is attempting to call render_header_nav_links(); a "