离线本地Unreal Engine文档

Unreal Engine的官方文档，一方面服务器太慢，一方面本地的文档打开就是没有渲染过的html，看起来实在太过难受，而且index中的链接都显示查无此文档，十分不方便，于是找到了建立本地文档库的方法，达到在本地跟官方服务器上阅读、搜索文档一样的效果。

docset-unreal-engine工具生成了Unreal Engine文档的docset，后用Zeal软件打开阅读，以下为具体步骤。

将本地官方文档生成docset

1. 找到官方文档所在地

当你下载了虚幻引擎Unreal Engine之后，本地是自带官方文档zip文件的，路径为：

<UnrealEngine Installed Path>\Engine\Documentation\Builds

这是我自己的路径以供参考
D:\App\UnrealEngine Machines\UE_5.3\Engine\Documentation\Builds

这个路径下面有俩个zip文件：

• BlueprintAPI-HTML.tgz (蓝图文档)
• CppAPI-HTML.tgz （C++文档）

2. 用docset-unreal-engine工具生成docset

（提前说下，docset-unreal-engine工具直接按教程运行在Windows中会报错，下文包含如何解决报错问题）

到docset-unreal-engine拿取代码
原版代码位置为：https://github.com/melMass/docset-unreal-engine，由于Github的网络限制问题，我附上原版代码和文档框架，方便阅读者获取。

project structure:
- unreal-engine-docset （root project folder）
| -- pyproject.toml
| -- unreal_engine_docset.py 

pyproject.toml:

[tool.poetry]
name = "unreal-engine-docset"
version = "0.1.0"
description = ""
license = "BSD-3-Clause"
authors = ["Thomas Mansencal <thomas.mansencal@gmail.com>"]
readme = "README.rst"

[tool.poetry.dependencies]
python = ">= 3.10, < 4"
click = ">= 8, < 9"
doc2dash = ">= 3, < 4"
lxml = "^5.1.0"
setuptools = "*"
tqdm = ">= 4, < 5"
typing-extensions = ">= 4, < 5"

[tool.poetry.group.dev.dependencies]
pre-commit = "*"
pyright = "*"

[flynt]
line_length = 999

[tool.isort]
ensure_newline_before_comments = true
force_grid_wrap = 0
include_trailing_comma = true
line_length = 88
multi_line_output = 3
skip_glob = ["colour/**/__init__.py"]
split_on_trailing_comma = true
use_parentheses = true

[tool.pyright]
reportMissingImports = false
reportMissingModuleSource = false
reportUnboundVariable = false
reportUnnecessaryCast = true
reportUnnecessaryTypeIgnorComment = true
reportUnsupportedDunderAll = false
reportUnusedExpression = false

[tool.pytest.ini_options]
addopts = "-n auto --dist=loadscope --durations=5"
filterwarnings = [
    "ignore::RuntimeWarning",
    "ignore::pytest.PytestCollectionWarning",
    "ignore::colour.utilities.ColourWarning",
    "ignore::colour.utilities.ColourRuntimeWarning",
    "ignore::colour.utilities.ColourUsageWarning",
    "ignore:Implicit None on return values is deprecated:DeprecationWarning",
    "ignore:Jupyter is migrating its paths:DeprecationWarning",
    "ignore:the imp module is deprecated:DeprecationWarning",
    "ignore:Method Nelder-Mead does not use gradient information:RuntimeWarning",
    "ignore:More than 20 figures have been opened:RuntimeWarning",
    "ignore:divide by zero encountered:RuntimeWarning",
    "ignore:invalid value encountered in:RuntimeWarning",
    "ignore:overflow encountered in:RuntimeWarning",
    "ignore:Matplotlib is currently using agg:UserWarning",
    "ignore:override the edgecolor or facecolor properties:UserWarning",
]

[tool.ruff]
target-version = "py39"
line-length = 88
select = [
    "A",   # flake8-builtins
    "ARG", # flake8-unused-arguments
    # "ANN", # flake8-annotations
    "B", # flake8-bugbear
    # "BLE", # flake8-blind-except
    "C4", # flake8-comprehensions
    # "C90", # mccabe
    # "COM", # flake8-commas
    "DTZ", # flake8-datetimez
    "D",   # pydocstyle
    "E",   # pydocstyle
    # "ERA", # eradicate
    # "EM", # flake8-errmsg
    "EXE", # flake8-executable
    "F",   # flake8
    # "FBT", # flake8-boolean-trap
    "G",   # flake8-logging-format
    "I",   # isort
    "ICN", # flake8-import-conventions
    "INP", # flake8-no-pep420
    "ISC", # flake8-implicit-str-concat
    "N",   # pep8-naming
    # "PD", # pandas-vet
    "PIE", # flake8-pie
    "PGH", # pygrep-hooks
    "PL",  # pylint
    # "PT", # flake8-pytest-style
    # "PTH", # flake8-use-pathlib [Enable]    "Q",   # flake8-quotes
    "RET", # flake8-return
    "RUF", # Ruff
    "S",   # flake8-bandit
    "SIM", # flake8-simplify
    "T10", # flake8-debugger
    "T20", # flake8-print
    # "TCH", # flake8-type-checking
    "TID", # flake8-tidy-imports
    "TRY", # tryceratops
    "UP",  # pyupgrade
    "W",   # pydocstyle
    "YTT", # flake8-2020
]
ignore = [
    "B008",
    "B905",
    "D104",
    "D200",
    "D202",
    "D205",
    "D301",
    "D400",
    "I001",
    "N801",
    "N802",
    "N803",
    "N806",
    "N813",
    "N815",
    "N816",
    "PGH003",
    "PIE804",
    "PLE0605",
    "PLR0911",
    "PLR0912",
    "PLR0913",
    "PLR0915",
    "PLR2004",
    "RET504",
    "RET505",
    "RET506",
    "RET507",
    "RET508",
    "TRY003",
    "TRY300",
]
typing-modules = ["colour.hints"]
fixable = ["B", "C", "E", "F", "PIE", "RUF", "SIM", "UP", "W"]

[tool.ruff.pydocstyle]
convention = "numpy"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

unreal_engine_docset.py

"""
Unreal Engine Docset
====================

Defines the objects to generate a `Dash <https://kapeli.com/dash>`__ compatible
docset from `Unreal Engine documentation <https://docs.unrealengine.com>`__:

-   :func:`generate_docset`
"""

from __future__ import annotations

import html
import logging
import multiprocessing
import os
import re
import shutil
import sqlite3
import tempfile
import time
import xml.etree.ElementTree as Et
from dataclasses import dataclass
from itertools import chain
from pathlib import Path
from typing import Callable, TypedDict, cast
from xml.dom import minidom

import click
import lxml.html
import setuptools.archive_util
from lxml import etree  # pyright: ignore
from lxml.html import fromstring, tostring
from tqdm.contrib.concurrent import process_map
from typing_extensions import Unpack

__author__ = "Thomas Mansencal"
__copyright__ = "Copyright 2024 Thomas Mansencal"
__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"
__maintainer__ = "Thomas Mansencal"
__email__ = "thomas.mansencal@gmail.com"
__status__ = "Production"

__all__ = [
    "Collector",
    "ApiInformation",
    "Entry",
    "MAPPING_API_TYPE_TO_ENTRY_TYPE",
    "chdir",
    "join_path",
    "read_xml_file",
    "collector_cpp_default",
    "collector_cpp_nohref",
    "COLLECTORS_CPP",
    "collector_blueprint_default",
    "COLLECTORS_BLUEPRINT",
    "collect_api_name_and_syntax",
    "collect_api_information",
    "process_cpp_html_file",
    "KwargsDocsetProcessor",
    "process_cpp_docset",
    "process_blueprint_html_file",
    "process_blueprint_docset",
    "process_python_docset",
    "generate_database",
    "generate_plist",
    "generate_docset",
]

logger = logging.getLogger(__name__)


@dataclass
class Collector:
    """
    Define a collector selecting data from *Unreal Engine* documentation.

    Parameters
    ----------
    type
         Entry type corresponding to a supported *Dash*
        `entry type <https://kapeli.com/docsets#supportedentrytypes>`__.
    predicate
        *XPath* expression predicate to collect the data.
    processor
        Callable processing the collected data.
    """

    type: str  # noqa: A003
    predicate: str
    processor: Callable


@dataclass(frozen=True)
class ApiInformation:
    """
    Define the *API* information for an *Unreal Engine* object and *Dash*
    documentation.

    Parameters
    ----------
    name
        Object *API* name.
    ue_type
        *Unreal Engine* object *API* type, e.g. ``UCLASS``.
    dash_type
        *Dash* documentation entry type, e.g. ``Class``.
    """

    name: str | None
    ue_type: str | None
    dash_type: str | None


@dataclass(frozen=True)
class Entry:
    """
    Define a *Dash* documentation entry.

    Parameters
    ----------
    name
        Object name.
    path
        Object path in the documentation, typically a relative html path.
    type
        *Dash* entry type, e.g. ``Class``.
    """

    name: str
    path: str
    type: str  # noqa: A003


MAPPING_API_TYPE_TO_ENTRY_TYPE: dict = {
    "class": "Class",
    "UCLASS": "Class",
    "struct": "Struct",
    "USTRUCT": "Struct",
    "union": "Union",
}
"""Mapping of *Unreal Engine* *API* type to *Dash* entry type."""


class chdir:
    """
    Define a context manager to change the current working directory.

    Parameters
    ----------
    path
        Desired working directory.
    """

    def __init__(self, path: Path | str):
        self.path = path
        self._old_cwd = []

    def __enter__(self):
        """Set the current working directory."""
        self._old_cwd.append(os.getcwd())
        os.chdir(self.path)

    def __exit__(self, *excinfo):
        """Restore the current working directory."""
        os.chdir(self._old_cwd.pop())


def join_path(parent: Path | str, name: str) -> str:
    """
    Join given parent and name into a path.

    Parameters
    ----------
    parent
        Parent to join.
    name
        Name to join.

    Returns
    -------
    :class:`str`
        Joined path.
    """

    parent = re.sub(r"\\?/?index.html$", "", str(parent))

    return f"{parent}/{name}"


def read_xml_file(xml_path: Path | str, attempts: int = 10) -> lxml.html.HtmlElement:
    """
    Attempt to read given *XML* file.

    Because of multiprocessing, it seems like on *macOS*, files might be
    accessed concurrently causing *XML* parsing failure.

    Parameters
    ----------
    xml_path
        Path of the *XML* file to read.
    attempts
        Number of attempts to try to read the file. One is usually required.

    Returns
    -------
    :class:`lxml.html.HtmlElement`
        *XML* element.
    """

    i = 0
    while i < attempts:
        try:
            with open(xml_path) as xml_file:
                xml = xml_file.read()

            return fromstring(xml.encode("utf-8"))
        except etree.ParserError:
            logger.debug(
                'Could not parse "%s" file on attempt %s, sleeping...', xml_path, i + 1
            )
            i += 1
            time.sleep(0.1)
            continue

    raise RuntimeError('Could not parse "%s" file!', xml_path)


def collector_cpp_default(
    elements: list[lxml.html.HtmlElement],
    parent_api_information: ApiInformation,  # noqa: ARG001
    html_path: Path,
) -> list[tuple[str, str]]:
    """
    Collect the *C++* *API* data for given elements.

    This is the default collector.

    Parameters
    ----------
    elements
        Elements to collect the data from.
    parent_api_information
        Parent *Unreal Engine* object and *Dash* documentation *API*
        information.
    html_path
        Path of the file the elements are contained into.

    Returns
    -------
    :class:`list`
        Collected data.
    """

    collection = []
    for element in elements:
        collected_path = join_path(html_path, element.attrib["href"])

        if not Path(collected_path).exists():
            continue

        collected_name = collect_api_information(read_xml_file(collected_path)).name

        collection.append((collected_name, collected_path))

    return collection


def collector_cpp_nohref(
    elements: list[lxml.html.HtmlElement],
    parent_api_information: ApiInformation,
    html_path: Path,
) -> list[tuple[str, str]]:
    """
    Collect the *C++* *API* data for given elements without an ``href``.

    Parameters
    ----------
    elements
        Elements to collect the data from.
    parent_api_information
        Parent *Unreal Engine* object and *Dash* documentation *API*
        information.
    html_path
        Path of the file the elements are contained into.

    Returns
    -------
    :class:`list`
        Collected data.
    """

    collection = []
    for element in elements:
        name = element.text_content()
        if parent_api_information.ue_type is not None:
            name = f"{parent_api_information.name}.{name}"

        collection.append((name, f"{html_path}#{name}"))

    return collection


COLLECTORS_CPP: tuple[Collector, ...] = (
    Collector(
        "Module",
        './/div[@class="modules-list"]//td[@class="name-cell"]/a[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
    Collector(
        "Class",
        './/div[@id="classes"]//td[@class="name-cell"][1]/a'
        '[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
    Collector(
        "Constructor",
        './/div[@id="constructor"]//td[@class="name-cell"][1]/a'
        '[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
    Collector(
        "Destructor",
        './/div[@id="destructor"]//td[@class="name-cell"][1]/a'
        '[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
    Collector(
        "Type",
        './/div[@id="typedefs"]//td[@class="name-cell"][1]/a'
        '[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
    Collector(
        "Enum",
        './/div[@id="enums"]//td[@class="name-cell"][1]/a[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
    Collector(
        "Variable",
        './/div[@id="variables"]//td[@class="name-cell"][2]/a'
        '[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
    Collector(
        "Variable",
        './/div[@id="deprecatedvariables"]//td[@class="name-cell"][2]/a'
        '[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
    Collector(
        "Variable",
        './/div[@id="variables"]//td[@class="name-cell"][2]/p',
        collector_cpp_nohref,
    ),
    Collector(
        "Variable",
        './/div[@id="deprecatedvariables"]//td[@class="name-cell"][2]/p',
        collector_cpp_nohref,
    ),
    Collector(
        "Constant",
        './/div[@id="constants"]//td[@class="name-cell"][1]/a'
        '[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
    Collector(
        "Function",
        './/div[starts-with(@id, "functions_")]//td[@class="name-cell"][2]/a'
        '[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
    Collector(
        "Function",
        './/div[starts-with(@id, "deprecatedfunctions")]//td[@class="name-cell"][2]/a'
        '[not(@class="dashAnchor")]',
        collector_cpp_default,
    ),
)
"""*Unreal Engine* documentation collectors for *C++*."""


def collector_blueprint_default(
    elements: list[lxml.html.HtmlElement],
    parent_api_information: ApiInformation,
    html_path: Path,
) -> list[tuple[str, str]]:
    """
    Collect the *Blueprint++* *API* data for given elements.

    This is the default collector.

    Parameters
    ----------
    elements
        Elements to collect the data from.
    parent_api_information
        Parent *Unreal Engine* object and *Dash* documentation *API*
        information.
    html_path
        Path of the file the elements are contained into.

    Returns
    -------
    :class:`list`
        Collected data.
    """

    collection = []
    for element in elements:
        collected_path = join_path(html_path, element.attrib["href"])

        if not Path(collected_path).exists():
            continue

        collected_name = collect_api_information(read_xml_file(collected_path)).name

        collection.append(
            (f"{parent_api_information.name}.{collected_name}", collected_path)
        )

    return collection


COLLECTORS_BLUEPRINT: tuple[Collector, ...] = (
    Collector(
        "Function",
        './/h2[@id="actions"]/following-sibling::div[@class="member-list"]//td[@class="name-cell"]/a'
        '[not(@class="dashAnchor")]',
        collector_blueprint_default,
    ),
    Collector(
        "Category",
        './/h2[@id="categories"]/following-sibling::div[@class="member-list"]//td[@class="name-cell"]/a'
        '[not(@class="dashAnchor")]',
        collector_blueprint_default,
    ),
)
"""*Unreal Engine* documentation collectors for *Blueprint*."""


def collect_api_name_and_syntax(
    xml: lxml.html.HtmlElement,
) -> tuple[str, str]:
    """
    Collect the *API* name and syntax from given *XML* element.

    Parameters
    ----------
    xml
        *XML* element to collect the *API* name and syntax from.

    Returns
    -------
    :class:`tuple`
        Collected *API* name and syntax.
    """

    title = next(iter(xml.xpath('.//h1[@id="H1TitleId"]/text()'))).strip()

    syntax = "\n".join(
        element.text_content()
        for element in xml.xpath('.//div[@class="simplecode_api"]/p')
    )

    return title, syntax


def collect_api_information(
    xml: lxml.html.HtmlElement,
) -> ApiInformation:
    """
    Collect the *API* information from given *XML* element.

    Parameters
    ----------
    xml
        *XML* element to collect the *API* information from.

    Returns
    -------
    :class:`ApiInformation`
        Collected *API* information.
    """

    api_name, api_syntax = collect_api_name_and_syntax(xml)
    for api_type, entry_type in MAPPING_API_TYPE_TO_ENTRY_TYPE.items():
        try:
            search = re.search(f"{api_type} {api_name}", api_syntax, re.MULTILINE)
        except re.error:
            continue

        if search is not None:
            return ApiInformation(api_name, api_type, entry_type)

    return ApiInformation(api_name, "object", "Object")


def process_cpp_html_file(
    html_path: Path,
    collectors: tuple = COLLECTORS_CPP,
    add_dash_anchors: bool = True,
) -> list[Entry]:
    """
    Process given *Unreal Engine* *C++* *HTML* file using given collectors.

    Parameters
    ----------
    html_path
         *HTML* file path to collect the data from.
    collectors
        Collectors used to process the *HTML* file.
    add_dash_anchors
        Whether to add *Dash* anchors to generate a
        `TOC <https://kapeli.com/docsets#tableofcontents>`__.

    Returns
    -------
    :class:`list`
        List of *Dash* documentation entries.
    """

    logger.info('Processing "%s" file...', html_path)

    def localiser(link):
        """Update given link to point to an actual *HTML* file"""

        index_path = html_path.parent / Path(link) / "index.html"

        if not index_path.exists():
            return link

        return f"{link}/index.html"

    xml = read_xml_file(html_path)
    xml.rewrite_links(localiser)

    api_information = collect_api_information(xml)

    has_dash_anchors = len(xml.xpath('.//a[@class="dashAnchor"]')) != 0

    entries = []
    for collector in collectors:
        elements = xml.xpath(collector.predicate)
        anchors = []
        for i, collection in enumerate(
            collector.processor(elements, api_information, html_path)
        ):
            collected_name, collected_html_path = collection

            if not Path(collected_html_path).exists():
                continue

            collected_type = collector.type

            # "class", "UCLASS", "struct", "USTRUCT" and "union" are classified
            # as "classes", we are providing more granularity.
            if collector.type == "Class":
                collected_xml = read_xml_file(collected_html_path)
                collected_api_information = collect_api_information(collected_xml)
                collected_type = collected_api_information.dash_type

            if add_dash_anchors and not has_dash_anchors:
                anchor_element = etree.Element("a")
                anchor_element.set("class", "dashAnchor")
                anchor_name = collected_name.split("::")[-1]

                suffix = ""
                if anchor_name in anchors:
                    count = anchors.count(anchor_name)
                    suffix = f" (Overload {count})"

                anchors.append(anchor_name)

                anchor_name = f"{anchor_name}{suffix}"

                anchor_element.set(
                    "name",
                    f"//apple_ref/cpp/{collected_type}/{html.escape(anchor_name)}",
                )
                elements[i].addprevious(anchor_element)

            entries.append(
                Entry(
                    cast(str, collected_name),
                    cast(str, collected_html_path),
                    cast(str, collected_type),
                )
            )

    with open(html_path, "w") as html_file:
        html_file.write(tostring(xml).decode("utf-8"))  # pyright: ignore

    return entries


class KwargsDocsetProcessor(TypedDict):
    """
    Define the keyword arguments for a docset processor.

    Parameters
    ----------
    api_directory
         Docset *API* path, e.g.``en-US/API``.
    docset_name
         Docset name, e.g.``UnrealEngineC++.docset``.
    online_url
        Online redirect *URL*.
    output_directory
         Docset output directory.
    unpacking_directory
         Docset unpacking directory.
    """

    api_directory: Path
    docset_name: str
    online_url: str
    output_directory: Path
    unpacking_directory: Path


def process_cpp_docset(**kwargs: Unpack[KwargsDocsetProcessor]) -> set[Entry]:
    """
    Process given *Unreal Engine* *C++* docset.

    Other Parameters
    ----------------
    kwargs
        See :class:`KwargsProcessor` class documentation.

    Returns
    -------
    :class:`set`
        Set of entries.
    """

    logger.info("Processing C++ docset...")

    api_directory = kwargs["api_directory"]

    css_path = api_directory / ".." / ".." / "Include" / "CSS" / "udn_public.css"

    with open(css_path, "a") as css_file:
        css_file.write(
            """
#maincol {
    height: unset !important;
}

#page_head, #navWrapper, #splitter, #footer {
    display: none !important;
}

#contentContainer {
    margin-left: 0 !important;
}

.toc {
    display: none !important;
}
"""
        )

    html_files = list(api_directory.glob("**/*.html"))

    return set(
        chain(
            *process_map(
                process_cpp_html_file,
                html_files,
                chunksize=16,
            )
        )
    )


def process_blueprint_html_file(
    html_path: Path,
    collectors: tuple = COLLECTORS_BLUEPRINT,
    add_dash_anchors: bool = True,
) -> list[Entry]:
    """
    Process given *Unreal Engine* *Blueprint* *HTML* file using given collectors.

    Parameters
    ----------
    html_path
         *HTML* file path to collect the data from.
    collectors
        Collectors used to process the *HTML* file.
    add_dash_anchors
        Whether to add *Dash* anchors to generate a
        `TOC <https://kapeli.com/docsets#tableofcontents>`__.

    Returns
    -------
    :class:`list`
        List of *Dash* documentation entries.
    """

    logger.info('Processing "%s" file...', html_path)

    def localiser(link):
        """Update given link to point to an actual *HTML* file"""

        index_path = html_path.parent / Path(link) / "index.html"

        if not index_path.exists():
            return link

        return f"{link}/index.html"

    xml = read_xml_file(html_path)
    xml.rewrite_links(localiser)

    api_information = collect_api_information(xml)

    has_dash_anchors = len(xml.xpath('.//a[@class="dashAnchor"]')) != 0

    entries = []
    for collector in collectors:
        elements = xml.xpath(collector.predicate)
        for i, collection in enumerate(
            collector.processor(elements, api_information, html_path)
        ):
            collected_name, collected_html_path = collection

            if not Path(collected_html_path).exists():
                continue

            collected_type = collector.type

            if add_dash_anchors and not has_dash_anchors:
                anchor_element = etree.Element("a")
                anchor_element.set("class", "dashAnchor")

                anchor_element.set(
                    "name",
                    f"//apple_ref/blueprint/{collected_type}/{html.escape(collected_name)}",
                )
                elements[i].addprevious(anchor_element)

            entries.append(
                Entry(
                    cast(str, collected_name),
                    cast(str, collected_html_path),
                    cast(str, collected_type),
                )
            )

    with open(html_path, "w") as html_file:
        html_file.write(tostring(xml).decode("utf-8"))  # pyright: ignore

    return entries


def process_blueprint_docset(**kwargs: Unpack[KwargsDocsetProcessor]) -> set[Entry]:
    """
    Process given *Unreal Engine* *Blueprint* docset.

    Other Parameters
    ----------------
    kwargs
        See :class:`KwargsProcessor` class documentation.

    Returns
    -------
    :class:`set`
        Set of entries.
    """

    logger.info("Processing Blueprint docset...")

    api_directory = kwargs["api_directory"]

    css_path = api_directory / ".." / ".." / "Include" / "CSS" / "udn_public.css"

    with open(css_path, "a") as css_file:
        css_file.write(
            """
#maincol {
    height: unset !important;
}

#page_head, #navWrapper, #splitter, #footer {
    display: none !important;
}

#contentContainer {
    margin-left: 0 !important;
}

.toc {
    display: none !important;
}
"""
        )

    html_files = list(api_directory.glob("**/*.html"))

    return set(
        chain(
            *process_map(
                process_blueprint_html_file,
                html_files,
                max_workers=multiprocessing.cpu_count() - 2,
                chunksize=16,
            )
        )
    )


def process_python_docset(**kwargs: Unpack[KwargsDocsetProcessor]) -> set[Entry]:
    """
    Process given *Unreal Engine* *Python* docset.

    This uses `doc2dash <https://github.com/hynek/doc2dash>`__ *API*.

    Other Parameters
    ----------------
    kwargs
        See :class:`KwargsProcessor` class documentation.

    Returns
    -------
    :class:`set`
        Set of entries.
    """

    from doc2dash.__main__ import main

    main.callback(  # pyright: ignore
        source=Path(kwargs["unpacking_directory"]),
        force=True,
        name=kwargs["docset_name"],
        quiet=False,
        verbose=True,
        destination=kwargs["output_directory"],
        add_to_dash=False,
        add_to_global=False,
        icon=None,
        icon_2x=None,
        index_page=Path("index.html"),
        enable_js=True,
        online_redirect_url=kwargs["online_url"],
        playground_url=None,
        parser_type=None,
        full_text_search="off",
    )

    return set()


def generate_database(
    database_path: Path, documents_directory: Path | str, entries: set[Entry]
) -> None:
    """
    Generate the *SQLite3* database storing the *Dash* entries.

    Parameters
    ----------
    database_path
        Path of the *SQLite3* database.
    documents_directory
        Path of the documents directory, e.g.
        ``UnrealEngineCpp.docset/Contents/Resources/Documents``.
    entries
        Entries to add to the *SQLite3* database.
    """

    logger.info("Creating Sqlite3 database...")

    database = sqlite3.connect(database_path)

    cursor = database.cursor()

    try:
        cursor.execute(
            "CREATE TABLE searchIndex("
            "id INTEGER PRIMARY KEY, "
            "name TEXT, "
            "type TEXT, "
            "path TEXT);"
        )
        cursor.execute("CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);")
    except sqlite3.OperationalError as error:
        logging.warning(str(error))

    documents_directory = f"{documents_directory}/".replace("\\", "/")

    for entry in sorted(entries, key=lambda x: x.name):
        cursor.execute(
            "INSERT OR IGNORE INTO searchIndex(name, type, path) VALUES (?,?,?)",
            (
                entry.name,
                entry.type,
                entry.path.replace("\\", "/").replace(documents_directory, ""),
            ),
        )

    database.commit()
    database.close()


def generate_plist(path: Path, mapping: list[tuple[str, str, str]]) -> None:
    """
    Generate the *PLIST* file for *Dash*.

    Parameters
    ----------
    path
        Path of the *PLIST* file, e.g.
        ``UnrealEngineCpp.docset/Contents/Info.plist``.
    mapping
        Mapping of the data to store in the *PLIST* file.
    """

    logger.info('Generating "%s" plist file...', path)

    plist_element = Et.Element("plist")
    plist_element.set("version", "1.0")

    mapping_element = Et.SubElement(plist_element, "dict")

    for key, type_, value in mapping:
        key_element = Et.SubElement(mapping_element, "key")
        key_element.text = key
        if type_ in ["string", "true", "false"]:
            value_element = Et.SubElement(mapping_element, type_)
            if type_ == "string":
                value_element.text = value

    xml = minidom.parseString(  # noqa: S318
        Et.tostring(plist_element, "utf-8")
    ).toprettyxml(indent="\t")
    xml = xml.split("\n", 1)[1]

    header = (
        '<?xml version="1.0" encoding="UTF-8"?>\n'
        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" '
        '"http://www.apple.com/DTDs/Propertylist-1.0.dtd">\n'
    )

    with open(path, "w") as plist_file:
        plist_file.write(header)
        plist_file.write(xml)


@click.command()
@click.option(
    "--input",
    required=True,
    type=click.Path(exists=True),
    help='Input "tgz" file to generate the docset from.',
)
@click.option(
    "--output",
    required=True,
    type=click.Path(exists=True),
    help="Output directory to generate to.",
)
def generate_docset(input: str, output: str) -> None:  # noqa: A002
    """
    Generate the *Dash* docset from given input *Unreal Engine* *tgz* file.

    Parameters
    ----------
    input
        *Unreal Engine* *tgz* file.
    output
        *Dash* docset output directory.
    """

    if "cpp" in Path(input).stem.lower():
        docset_type = "c++"
    elif "blueprint" in Path(input).stem.lower():
        docset_type = "blueprint"
    elif "python" in Path(input).stem.lower():
        docset_type = "python"
    else:
        logging.error("Unsupported docset type, exiting!")
        return

    output_directory = Path(output)

    docset_name = f"UnrealEngine{docset_type.title()}API.docset"
    docset_directory = output_directory / docset_name
    contents_directory = docset_directory / "Contents"
    resources_directory = contents_directory / "Resources"
    documents_directory = resources_directory / "Documents"
    documents_directory.mkdir(parents=True, exist_ok=True)

    if docset_type == "c++":
        api_directory = documents_directory / "en-US" / "API"
        label = "C++"
        processor = process_cpp_docset
        online_url = "https://docs.unrealengine.com/en-US/API"
        unpacking_directory = documents_directory
    elif docset_type == "blueprint":
        api_directory = documents_directory / "en-US" / "BlueprintAPI"
        label = "Blueprint"
        processor = process_blueprint_docset
        online_url = "https://docs.unrealengine.com/en-US/BlueprintAPI"
        unpacking_directory = documents_directory
    elif docset_type == "python":
        api_directory = documents_directory
        label = "Python"
        processor = process_python_docset
        online_url = "https://docs.unrealengine.com/en-US/PythonAPI"
        temporary_directory = tempfile.TemporaryDirectory(delete=False)
        unpacking_directory = Path(temporary_directory.name)
    else:
        logging.error("Unsupported docset type, exiting!")
        return

    docset_label = f"Unreal Engine - {label} API"

    logger.info('Extracting "%s" archive to "%s"...', input, unpacking_directory)
    setuptools.archive_util.unpack_archive(input, str(unpacking_directory))

    with chdir(api_directory):  # pyright: ignore
        entries = processor(
            api_directory=api_directory,
            docset_name=docset_name,
            online_url=online_url,
            output_directory=output_directory,
            unpacking_directory=unpacking_directory,
        )

    if docset_type in ["c++", "blueprint"]:
        generate_database(
            resources_directory / "docSet.dsidx", documents_directory, entries
        )

    mapping = [
        ("CFBundleIdentifier", "string", docset_name),
        ("CFBundleName", "string", docset_label),
        ("DashDocSetDeclaredInStyle", "string", "originalName"),
        ("DashDocSetFallbackURL", "string", online_url),
        ("DashDocSetFamily", "string", "python"),
        ("DocSetPlatformFamily", "string", "Unreal Engine"),
        ("isDashDocset", "true", None),
        ("isJavaScriptEnabled", "true", None),
    ]

    if docset_type == "c++":
        mapping.append(("dashIndexFilePath", "string", "en-US/API/index.html"))
    elif docset_type == "blueprint":
        mapping.append(("dashIndexFilePath", "string", "en-US/BlueprintAPI/index.html"))
    elif docset_type == "python":
        mapping.append(("dashIndexFilePath", "string", "index.html"))

    generate_plist(contents_directory / "Info.plist", mapping)

    if docset_type == "python":
        temporary_directory.cleanup()

    shutil.copyfile(
        Path(__file__).parent / "icon.png", Path(docset_directory) / "icon.png"
    )


if __name__ == "__main__":
    logging.basicConfig()

    logging.getLogger().setLevel(logging.INFO)

    generate_docset()

生成步骤

1. 参照peotry官网安装poetry以build这个project：https://python-poetry.org/docs/#installing-with-pipx

   我用的是Windows，所以步骤为：(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

2. 用poetry build project

   cd unreal-engine-docset
   poetry install

3. 安装其他依赖包
   发现有些包运行的时候提示缺乏，这里补上
   pip install lxml tqdm typing_extensions
4. 修改运行bug
   在Windows上运行的时候碰到报错：

   unreal_engine_docset.py", line 215, in read_xml_file
   xml = xml_file.read()
         ^^^^^^^^^^^^^^^
   UnicodeDecodeError: 'gbk' codec can't decode byte 0x94 in position 19959: illegal multibyte sequence

   应该是文件打开格式的问题，所以将 unreal_engine_docset.py 214行修改了，添加了utf-8的打开格式：

   # with open(xml_path) as xml_file:
   with open(xml_path, encoding="utf-8") as xml_file:

   这样就不会运行一半报错了！
5. 运行生成docset
   这里建议把output的路径直接指到Zeal软件下的storage文件夹地址，以防之后要拷贝过去，10GB的文件太慢了。

   python .\unreal_engine_docset.py --input <tgz file path> --output <your docset store path>
   
   <!-- My sample cmd -->
   python .\unreal_engine_docset.py --input "D:\App\UnrealEngine Machines\UE_5.3\Engine\Documentation\Builds\CppAPI-HTML.tgz" --output "D:\App\Zeal\storage"

   成功后会在目标路径生成UnrealEngineC++API.docset类似文件。

3. 安装Zeal软件

在官方Zeal网站上下载软件并安装：https://zealdocs.org/download.html

找到storage文件夹位置
打开Zeal，在 Customize 下面，选择 Preferences -> Docset Storage，设置为你自己想要的位置。

3. 用Zeal打开文档

Zeal没有什么导入文档的按钮，所有在storage文件夹下的docset都会被读入，所以把生成好的docset文件夹放入storage 文件夹，重启Zeal就可以看到了！

大功告成，希望对你有帮助！！！