# Copyright 2023 The Pigweed Authors
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
# use this file except in compliance with the License. You may obtain a copy of
# the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations under
# the License.
"""Generates content related to Pigweed module metadata on pigweed.dev.

This file implements the following pigweed.dev features:

* The `.. pigweed-module::` and `.. pigweed-module-subpage::` directives.
* The auto-generated "Source code" and "Issues" URLs that appear in the site
  nav for each module.

Everything is implemented through the Sphinx Extension API.
"""

from dataclasses import dataclass
import json
import os
import sys
from typing import cast, TypeVar

# We use BeautifulSoup for certain docs rendering features. It may not be
# available in downstream projects. If so, no problem. We fall back to simpler
# docs rendering.
# pylint: disable=import-error
try:
    from bs4 import BeautifulSoup  # type: ignore
    from bs4.element import Tag as HTMLTag  # type: ignore

    bs_enabled = True
except ModuleNotFoundError:
    bs_enabled = False

try:
    import jsonschema  # type: ignore

    jsonschema_enabled = True
except ModuleNotFoundError:
    jsonschema_enabled = False
# pylint: enable=import-error

import docutils
from docutils import nodes
from docutils.nodes import Element
import docutils.statemachine

# pylint: disable=consider-using-from-import
import docutils.parsers.rst.directives as directives  # type: ignore

# pylint: enable=consider-using-from-import
from sphinx.addnodes import document as Document
from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment
from sphinx.util.docutils import SphinxDirective

from sphinx_design.cards import CardDirective

EnvAttrT = TypeVar('EnvAttrT')


# The module metadata is exposed as a global because it's used as read-only
# data. Opening and reading the metadata file in one of the event handlers
# would cause hundreds of filesystem reads on each build because those event
# handlers fire once for each docs page that's built.
try:  # Bazel location for the data
    from python.runfiles import runfiles  # type: ignore

    script_dir = os.path.dirname(os.path.abspath(__file__))
    schema_file = f"{script_dir}/../module_metadata_schema.json"
    metadata_file = f"{script_dir}/../module_metadata.json"
except ImportError:  # GN location for the data
    schema_file = f'{os.environ["PW_ROOT"]}/docs/module_metadata_schema.json'
    metadata_file = f'{os.environ["PW_ROOT"]}/docs/module_metadata.json'
with open(schema_file, 'r') as f:
    schema = json.load(f)
with open(metadata_file, 'r') as f:
    metadata = json.load(f)
# Make sure the metadata matches its schema. Raise an uncaught exception
# if not.
if jsonschema_enabled:
    jsonschema.validate(metadata, schema)


@dataclass
class ParsedBody:
    topnav: str
    body_without_topnav: str


class EnvMetadata:
    """Easier access to the Sphinx `env` for custom metadata.

    You can store things in the Sphinx `env`, which is just a dict. But each
    time you do, you have to handle the possibility that the key you want
    hasn't been set yet, and set it to a default. The `env` is also untyped,
    so you have to cast the value you get to whatever type you expect it to be.

    Or you can use this class to define your metadata keys up front, and just
    access them like: `value = EnvMetadata(env).my_value`

    ... which will handle initializing the value if it hasn't been yet and
    provide you a typed result.
    """

    def __init__(self, env: BuildEnvironment):
        self._env = env

    def _get_env_attr(self, attr: str, default: EnvAttrT) -> EnvAttrT:
        if not hasattr(self._env, attr):
            value: EnvAttrT = default
            setattr(self._env, attr, value)
        else:
            value = getattr(self._env, attr)

        return value

    @property
    def pw_parsed_bodies(self) -> dict[str, ParsedBody]:
        default: dict[str, ParsedBody] = {}
        return self._get_env_attr('pw_module_nav', default)


def get_languages(module_name: str) -> list[str] | None:
    """Returns the list of languages that a module supports.

    Args:
        module_name: The module to look up.

    Returns:
        A list of programming languages that the module supports, or ``None``
        if this has not been defined in ``//docs/sphinx/module_metadata.json``.
    """
    if module_name not in metadata:
        return None
    if 'languages' not in metadata[module_name]:
        return None
    return metadata[module_name]['languages']


def get_status(module_name: str) -> str:
    """Returns the status of a module.

    Preconditions:
        The status must be defined in ``//docs/sphinx/module_metadata.json``.

    Args:
        module_name: The module to look up.

    Returns:
        The status of the module as a string.
    """
    if module_name not in metadata:
        sys.exit(f'{module_name} not found in {metadata_file}')
    if 'status' not in metadata[module_name]:
        sys.exit(f'{module_name}.status not found in {metadata_file}')
    return metadata[module_name]['status']


def get_tagline(module_name: str) -> str | None:
    """Returns the tagline for a module.

    Args:
        module_name: The module to look up.

    Returns:
        The module's tagline or ``None`` if no tagline has been defined
        in ``//docs/sphinx/module_metadata.json``.
    """
    if module_name not in metadata:
        return None
    if 'tagline' not in metadata[module_name]:
        return None
    return metadata[module_name]['tagline']


def get_code_size(module_name: str) -> str | None:
    """Returns the code size impact summary for a module.

    Args:
        module_name: The module to look up.

    Returns:
        The code size impact summary as a string or ``None`` if no summary
        has been defined in ``//docs/sphinx/module_metadata.json``.
    """
    if module_name not in metadata:
        return None
    if 'size' not in metadata[module_name]:
        return None
    return metadata[module_name]['size']


def status_badge(module_status: str) -> str:
    """Given a module status, return the status badge for rendering."""
    # Use a different badge for each module status value.
    # https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html#badges
    status_to_badge = {
        'stable': 'primary',
        'unstable': 'secondary',
        'experimental': 'warning',
        'deprecated': 'danger',
    }
    badge = status_to_badge[module_status]
    role = f':bdg-{badge}:'
    return role + f'`{module_status.title()}`'


def cs_url(module_name: str) -> str:
    """Return the codesearch URL for the given module."""
    return f'https://cs.opensource.google/pigweed/pigweed/+/main:{module_name}/'


def issues_url(module_name: str) -> str:
    """Returns open issues that mention the given module name."""
    return f'https://issues.pigweed.dev/issues?q={module_name}%20status:open'


def rustdoc_url(module_name: str) -> str:
    """Returns the rustdoc URL for a given module."""
    return f'https://pigweed.dev/rustdoc/{module_name}'


def doxygen_url(module_name: str) -> str:
    """Returns the Doxygen URL for a given module."""
    module_name = module_name.replace("_", "__")
    return f'https://pigweed.dev/doxygen/group__{module_name}.html'


def concat_tags(*tag_lists: list[str]) -> list[str]:
    """Given a list of tag lists, return them concat'ed and ready for render."""

    all_tags = tag_lists[0]

    for tag_list in tag_lists[1:]:
        if len(tag_list) > 0:
            all_tags.append(':octicon:`dot-fill`')
            all_tags.extend(tag_list)

    return all_tags


def create_topnav(
    subtitle: str | None,
    extra_classes: list[str] | None = None,
) -> nodes.Node:
    """Create the nodes for the top title and navigation bar."""

    topnav_classes = (
        ['pw-topnav'] + extra_classes if extra_classes is not None else []
    )

    topnav_container = nodes.container(classes=topnav_classes)

    if subtitle:
        subtitle_node = nodes.paragraph(
            classes=['pw-topnav-subtitle'],
            text=subtitle,
        )
        topnav_container += subtitle_node

    return topnav_container


class PigweedModuleDirective(SphinxDirective):
    """Directive registering module metadata, rendering title & info card."""

    required_arguments = 0
    final_argument_whitespace = True
    has_content = True
    option_spec = {'name': directives.unchanged_required}

    def _try_get_option(self, option: str):
        """Try to get an option by name and raise on failure."""

        try:
            return self.options[option]
        except KeyError:
            raise self.error(f' :{option}: option is required')

    def _maybe_get_option(self, option: str):
        """Try to get an option by name and return None on failure."""
        return self.options.get(option, None)

    def run(self) -> list[nodes.Node]:
        module_name = self._try_get_option('name')
        tagline = get_tagline(module_name)
        status = get_status(module_name)

        status_tags: list[str] = [
            status_badge(status),
        ]

        languages = get_languages(module_name)
        language_tags = []
        if languages:
            for language in languages:
                language_tags.append(f':bdg-info:`{language}`')

        code_size_impact = []

        code_size_text = get_code_size(module_name)
        if code_size_text:
            code_size_impact.append(f'**Code Size Impact:** {code_size_text}')

        # Move the directive content into a section that we can render wherever
        # we want.
        raw_content = cast(list[str], self.content)  # type: ignore
        content = nodes.paragraph()
        self.state.nested_parse(raw_content, 0, content)

        # The card inherits its content from this node's content, which we've
        # already pulled out. So we can replace this node's content with the
        # content we need in the card.
        self.content = docutils.statemachine.StringList(
            concat_tags(status_tags, language_tags, code_size_impact)
        )

        card = CardDirective.create_card(
            inst=self,
            arguments=[],
            options={},
        )

        topbar = create_topnav(
            tagline,
            ['pw-module-index'],
        )

        return [topbar, card, content]


class PigweedModuleSubpageDirective(PigweedModuleDirective):
    """Directive registering module metadata, rendering title & info card."""

    required_arguments = 0
    final_argument_whitespace = True
    has_content = True
    option_spec = {
        'name': directives.unchanged_required,
        'nav': directives.unchanged_required,
    }

    def run(self) -> list[nodes.Node]:
        module_name = self._try_get_option('name')
        tagline = get_tagline(module_name)
        # Prepend the module name on sub-pages so that it's very clear what
        # the tagline is referring to.
        tagline = f'{module_name}: {tagline}'

        topbar = create_topnav(
            tagline,
            ['pw-module-subpage'],
        )

        return [topbar]


def _parse_body(body: str) -> ParsedBody:
    """From the `body` HTML, return the topnav and the body without topnav.

    The fundamental idea is this: Our Sphinx directives can only render nodes
    *within* the docutils doc, but we want to elevate the top navbar *outside*
    of that doc into the web theme. Sphinx by itself provides no mechanism for
    this, since it's model looks something like this:

      ┌──────────────────┐
      │ Theme            │
      │  ┌──────────────┐│    When Sphinx builds HTML, the output is plain HTML
      │  │ Sphinx HTML  ││    with a structure defined by docutils. Themes can
      │  │              ││    build *around* that and cascade styles down *into*
      │  │              ││    that HTML, but there's no mechanism in the Sphinx
      │  └──────────────┘│    build to render docutils nodes in the theme.
      └──────────────────┘

    The escape hatch is this:
    - Render things within the Sphinx HTML output (`body`)
    - Use Sphinx theme templates to run code during the final render phase
    - Extract the HTML from the `body` and insert it in the theme via templates

    So this function extracts the things that we rendered in the `body` but
    actually want in the theme (the top navbar), returns them for rendering in
    the template, and returns the `body` with those things removed.
    """
    if not bs_enabled:
        return ParsedBody('', body)

    def _add_class_to_tag(tag: HTMLTag, classname: str) -> None:
        tag['class'] = tag.get('class', []) + [classname]  # type: ignore

    def _add_classes_to_tag(
        tag: HTMLTag, classnames: str | list[str] | None
    ) -> None:
        tag['class'] = tag.get('class', []) + classnames  # type: ignore

    html = BeautifulSoup(body, features='html.parser')

    # Render the doc unchanged, unless it has the module doc topnav
    if (topnav := html.find('div', attrs={'class': 'pw-topnav'})) is None:
        return ParsedBody('', body)

    assert isinstance(topnav, HTMLTag)

    # Find the topnav title and subtitle
    topnav_title = topnav.find('p', attrs={'class': 'pw-topnav-title'})
    topnav_subtitle = topnav.find('p', attrs={'class': 'pw-topnav-subtitle'})
    assert isinstance(topnav_title, HTMLTag)
    assert isinstance(topnav_subtitle, HTMLTag)

    # Find the single `h1` element, the doc's canonical title
    doc_title = html.find('h1')
    assert isinstance(doc_title, HTMLTag)

    topnav_str = ''

    if 'pw-module-index' in topnav['class']:
        # Take the standard Sphinx/docutils title and add topnav styling
        _add_class_to_tag(doc_title, 'pw-topnav-title')
        # Replace the placeholder title in the topnav with the "official" `h1`
        topnav_title.replace_with(doc_title)
        # Promote the subtitle to `h2`
        topnav_subtitle.name = 'h2'
        # We're done mutating topnav; write it to string for rendering elsewhere
        topnav_str = str(topnav)
        # Destroy the instance that was rendered in the document
        topnav.decompose()

    elif 'pw-module-subpage' in topnav['class']:
        # Take the title from the topnav (the module name), promote it to `h1`
        topnav_title.name = 'h1'
        # Add the heading link, but pointed to the module index page
        heading_link = html.new_tag(
            'a',
            attrs={
                'class': ['headerlink'],
                'href': 'docs.html',
                'title': 'Permalink to module index',
            },
        )
        heading_link.string = '#'
        topnav_title.append(heading_link)
        # Promote the subtitle to `h2`
        topnav_subtitle.name = 'h2'
        # We're done mutating topnav; write it to string for rendering elsewhere
        topnav_str = str(topnav)
        # Destroy the instance that was rendered in the document
        topnav.decompose()

    return ParsedBody(topnav_str, str(html))


def setup_parse_body(_app, _pagename, _templatename, context, _doctree):
    def parse_body(body: str) -> ParsedBody:
        return _parse_body(body)

    context['parse_body'] = parse_body


def fix_canonical_url(canonical_url: str | None) -> str | None:
    """Rewrites the canonical URL for `pigweed.dev/*/docs.html` pages.

    Our server is configured to remove `docs.html` from URLs. E.g.
    pigweed.dev/pw_string/docs.html` redirects to `pigweed.dev/pw_string`.
    To improve our SEO, the `<link rel="canonical" href="..."/>` tag in our
    HTML should match the URL that the server provides.

    Args:
        docname:
            Basically the relative path to the doc, except `.rst` is omitted
            from the filename. E.g. `pw_string/docs`.
        canonical_url:
            The default canonical URL that Sphinx has generated for the doc.

    Returns:
        The corrected canonical URL if the page would normally end with
        `docs.html`, otherwise the original canonical URL value unmodified.
    """
    if canonical_url is None or not canonical_url.endswith('/docs.html'):
        return canonical_url
    canonical_url = canonical_url.replace('/docs.html', '/')
    return canonical_url


def on_html_page_context(
    app: Sphinx,  # pylint: disable=unused-argument
    docname: str,  # pylint: disable=unused-argument
    templatename: str,  # pylint: disable=unused-argument
    context: dict[str, str | None] | None,
    doctree: Document,  # pylint: disable=unused-argument
) -> None:
    """Handles modifications to HTML page metadata, e.g. canonical URLs.

    Args:
        docname:
            Basically the relative path to the doc, except `.rst` is omitted
            from the filename. E.g. `pw_string/docs`.
        context:
            A dict containing the HTML page's metadata.

    Returns:
        None. Modifications happen to the HTML metadata in-place.
    """
    canonical_url_key = 'pageurl'
    if context is None or canonical_url_key not in context:
        return
    canonical_url = context[canonical_url_key]
    context[canonical_url_key] = fix_canonical_url(canonical_url)


def should_add_rust_link(module_name: str, languages: list[str] | None) -> bool:
    if languages is None:
        return False
    ignore = [
        # TODO: https://pwbug.dev/424641732 - Remove this.
        'pw_kernel',
    ]
    if module_name in ignore:
        return False
    if 'Rust' not in languages:
        return False
    return True


# TODO: https://pwbug.dev/426012010 - Make this logic general,
# like how `should_add_rust_link` does it.
def should_add_doxygen_link(module_name) -> bool:
    ok = [
        'pw_alignment',
        'pw_allocator',
        'pw_analog',
        'pw_async',
        'pw_async2',
        'pw_async_basic',
        'pw_base64',
        'pw_bloat',
        'pw_bluetooth',
        'pw_bluetooth_proxy',
        'pw_bluetooth_sapphire',
        'pw_build',
        'pw_bytes',
        'pw_channel',
        'pw_chre',
        'pw_chrono',
        'pw_clock_tree',
        'pw_clock_tree_mcuxpresso',
        'pw_containers',
        'pw_crypto',
        'pw_digital_io',
        'pw_digital_io_mcuxpresso',
        'pw_display',
        'pw_elf',
        'pw_function',
        'pw_hdlc',
        'pw_hex_dump',
        'pw_i2c',
        'pw_i2c_linux',
        'pw_interrupt',
        'pw_json',
        'pw_kvs',
        'pw_log',
        'pw_log_tokenized',
        'pw_malloc',
        'pw_multibuf',
        'pw_numeric',
        'pw_perf_test',
        'pw_persistent_ram',
        'pw_polyfill',
        'pw_preprocessor',
        'pw_protobuf',
        'pw_random',
        'pw_result',
        'pw_rpc',
        'pw_span',
        'pw_spi',
        'pw_status',
        'pw_stream',
        'pw_stream_uart_linux',
        'pw_string',
        'pw_sync',
        'pw_sys_io',
        'pw_system',
        'pw_thread',
        'pw_tokenizer',
        'pw_toolchain',
        'pw_trace_tokenized',
        'pw_transfer',
        'pw_uart',
        'pw_uuid',
        'pw_varint',
        'pw_work_queue',
    ]
    return module_name in ok


def add_links(module_name: str, toctree: Element) -> None:
    """Adds source code and issues URLs to a module's table of contents tree.

    This function is how we auto-generate the source code and issues URLs
    that appear for each module in the pigweed.dev site nav.

    Args:
        module_name:
            The Pigweed module that we're creating links for.
        toctree:
            The table of contents tree from that module's homepage.

    Returns:
        `None`. `toctree` is modified in-place.
    """
    languages = get_languages(module_name)
    ignore = [
        # TODO: https://pwbug.dev/424641732 - Remove this.
        'pw_kernel',
    ]
    if should_add_rust_link(module_name, languages):
        rustdoc = ('Rust API reference', rustdoc_url(module_name))
        toctree['entries'] += [rustdoc]
        toctree['rawentries'] += [rustdoc[0]]
    if should_add_doxygen_link(module_name):
        doxygen = ('C/C++ API reference', doxygen_url(module_name))
        toctree['entries'] += [doxygen]
        toctree['rawentries'] += [doxygen[0]]
    src = ('Source code', cs_url(module_name))
    issues = ('Issues', issues_url(module_name))
    # Maintenance tip: the trick here is to create the `toctree` the same way
    # that Sphinx generates it. When in doubt, enable logging in this file,
    # manually modify the `.. toctree::` directive on a module's homepage, log
    # out `toctree` from somewhere in this script (you should see an XML-style
    # node), and then just make sure your code modifies the `toctree` the same
    # way that Sphinx generates it.
    toctree['entries'] += [src, issues]
    toctree['rawentries'] += [src[0], issues[0]]


def find_first_toctree(doctree: Document) -> Element | None:
    """Finds the first `toctree` (table of contents tree) node in a `Document`.

    Args:
        doctree:
            The content of a doc, represented as a tree of Docutils nodes.

    Returns:
        The first `toctree` node found in `doctree` or `None` if none was
        found.
    """
    for node in doctree.traverse(nodes.Element):
        if node.tagname == 'toctree':
            return node
    return None


def parse_module_name(docname: str) -> str:
    """Extracts a Pigweed module name from a Sphinx docname.

    Preconditions:
        `docname` is assumed to start with `pw_`. I.e. the docs are assumed to
        have a flat directory structure, where the first directory is the name
        of a Pigweed module.

    Args:
        docname:
            Basically the relative path to the doc, except `.rst` is omitted
            from the filename. E.g. `pw_string/docs`.

    Returns:
        Just the Pigweed module name, e.g. `pw_string`.
    """
    tokens = docname.split('/')
    return tokens[0]


def on_doctree_read(app: Sphinx, doctree: Document) -> None:
    """Event handler that enables manipulating a doc's Docutils tree.

    Sphinx fires this listener after it has parsed a doc's reStructuredText
    into a tree of Docutils nodes. The listener fires once for each doc that's
    processed.

    In general, this stage of the Sphinx event lifecycle can only be used for
    content changes that do not affect the Sphinx build environment [1]. For
    example, creating a `toctree` node at this stage does not work, but
    inserting links into a pre-existing `toctree` node is OK.

    Args:
        app:
            Our Sphinx docs build system.
        doctree:
            The doc content, structured as a tree.

    Returns:
        `None`. The main modifications happen in-place in `doctree`.

    [1] See link in `on_source_read()`
    """
    docname = app.env.docname
    if not is_module_homepage(docname):
        return
    toctree = find_first_toctree(doctree)
    if toctree is None:
        # `add_toctree_to_module_homepage()` should ensure that every
        # `pw_*/docs.rst` file has a `toctree` node but if something went wrong
        # then we should bail.
        sys.exit(f'[module_metadata.py] error: toctree missing in {docname}')
    module_name = parse_module_name(docname)
    add_links(module_name, toctree)


def is_module_homepage(docname: str) -> bool:
    """Determines if a doc is a module homepage.

    Any doc that matches the pattern `pw_*/docs.rst` is considered a module
    homepage. Watch out for the false positive of `pw_*/*/docs.rst`.

    Preconditions:
        `docname` is assumed to start with `pw_`. I.e. the docs are assumed to
        have a flat directory structure, where the first directory is the name
        of a Pigweed module.

    Args:
        docname:
            Basically the relative path to the doc, except `.rst` is omitted
            from the filename.

    Returns:
        `True` if the doc is a module homepage, else `False`.
    """
    tokens = docname.split('/')
    if len(tokens) != 2:
        return False
    if not tokens[0].startswith('pw_'):
        return False
    if tokens[1] != 'docs':
        return False
    return True


def add_toctree_to_module_homepage(docname: str, source: str) -> str:
    """Appends an empty `toctree` to a module homepage.

    Note that this function only needs to create the `toctree` node; it doesn't
    need to fully populate the `toctree`. Inserting links later via the more
    ergonomic Docutils API works fine.

    Args:
        docname:
            Basically the relative path to `source`, except `.rst` is omitted
            from the filename.
        source:
            The reStructuredText source code of `docname`.

    Returns:
        For module homepages that did not already have a `toctree`, the
        original contents of `source` plus an empty `toctree` is returned.
        For all other cases, the original contents of `source` are returned
        with no modification.
    """
    # Don't do anything if the page is not a module homepage, i.e. its
    # `docname` doesn't match the pattern `pw_*`/docs`.
    if not is_module_homepage(docname):
        return source
    # Don't do anything if the module homepage already has a `toctree`.
    if '.. toctree::' in source:
        return source
    # Append an empty `toctree` to the content.
    # yapf: disable
    return (
        f'{source}\n\n'
        '.. toctree::\n'
        '   :hidden:\n'
        '   :maxdepth: 1\n'
    )
    # yapf: enable
    # Python formatting (yapf) is disabled in the return statement because the
    # formatter tries to change it to a less-readable single line string.


# inclusive-language: disable
def on_source_read(
    app: Sphinx,  # pylint: disable=unused-argument
    docname: str,
    source: list[str],
) -> None:
    """Event handler that enables manipulating a doc's reStructuredText.

    Sphinx fires this event early in its event lifecycle [1], before it has
    converted a doc's reStructuredText (reST) into a tree of Docutils nodes.
    The listener fires once for each doc that's processed.

    This is the place to make docs changes that have to propagate across the
    site. Take our use case of adding a link in the site nav to each module's
    source code. To do this we need a `toctree` (table of contents tree) node
    on each module's homepage; the `toctree` is where we insert the source code
    link. If we try to dynamically insert the `toctree` node via the Docutils
    API later in the event lifecycle, e.g. during the `doctree-read` event, we
    have to do a bunch of complex and fragile logic to make the Sphinx build
    environment [2] aware of the new node. It's simpler and more reliable to
    just insert a `.. toctree::` directive into the doc source before Sphinx
    has processed the doc and then let Sphinx create its build environment as
    it normally does. We just have to make sure the reStructuredText we're
    injecting into the content is syntactically correct.

    Args:
        app:
            Our Sphinx docs build system.
        docname:
            Basically the relative path to `source`, except `.rst` is omitted
            from the filename.
        source:
            The reStructuredText source code of `docname`.

    Returns:
        None. `source` is modified in-place.

    [1] www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
    [2] www.sphinx-doc.org/en/master/extdev/envapi.html
    """
    # inclusive-language: enable
    # If a module homepage doesn't have a `toctree`, add one.
    source[0] = add_toctree_to_module_homepage(docname, source[0])


def setup(app: Sphinx) -> dict[str, bool]:
    """Hooks the extension into our Sphinx docs build system.

    This runs only once per docs build.

    Args:
        app:
            Our Sphinx docs build system.

    Returns:
        A dict that provides Sphinx info about our extension.
    """
    # Register the `.. pigweed-module::` and `.. pigweed-module-subpage::`
    # directives that are used on `pw_*/*.rst` pages.
    app.add_directive('pigweed-module', PigweedModuleDirective)
    app.add_directive('pigweed-module-subpage', PigweedModuleSubpageDirective)
    # inclusive-language: disable
    # Register the Sphinx event listeners that automatically generate content
    # for `pw_*/*.rst` pages:
    # www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
    # inclusive-language: enable
    app.connect('source-read', on_source_read)
    app.connect('doctree-read', on_doctree_read)
    app.connect('html-page-context', on_html_page_context)
    return {
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }