disnake

1
# SPDX-License-Identifier: MIT
2
from __future__ import annotations
3

4
import json
5
from pathlib import Path
6
from typing import TYPE_CHECKING, Dict
7

8
from sphinx.application import Sphinx
9
from sphinx.util.fileutil import copy_asset_file
10

11
if TYPE_CHECKING:
12
    from ._types import SphinxExtensionMeta
13

14
SCRIPT_PATH = "_templates/api_redirect.js_t"
15

16

17
def collect_redirects(app: Sphinx):
18
    # mapping of html node id (i.e., thing after "#" in URLs) to the correct page name
19
    # e.g, api.html#disnake.Thread => api/channels.html
20
    mapping: Dict[str, str] = {}
21

22
    # see https://www.sphinx-doc.org/en/master/extdev/domainapi.html#sphinx.domains.Domain.get_objects
23
    domain = app.env.domains["py"]
24
    for _, _, _, document, html_node_id, _ in domain.get_objects():
25
        mapping[html_node_id] = document + ".html"
26

27
    return mapping
28

29

30
def copy_redirect_script(app: Sphinx, exception: Exception) -> None:
31
    if app.builder.format != "html" or exception:
32
        return
33

34
    redirect_mapping = collect_redirects(app)
35
    context = {"redirect_data": json.dumps(redirect_mapping)}
36

37
    # sanity check
38
    assert Path(SCRIPT_PATH).exists()  # noqa: S101
39

40
    copy_asset_file(
41
        SCRIPT_PATH,
42
        str(Path(app.outdir, "_static", "api_redirect.js")),
43
        context=context,
44
    )
45

46

47
def setup(app: Sphinx) -> SphinxExtensionMeta:
48
    app.connect("build-finished", copy_redirect_script)
49

50
    return {
51
        "parallel_read_safe": True,
52
        "parallel_write_safe": True,
53
    }
54