mystx

mystx#

mystx - 现代化 Sphinx 文档主题。

This module provides a custom Sphinx theme for creating beautiful, modern documentation. The theme includes configuration management, styling, and integration with Sphinx.

1.  Submodules#

2.  Attributes#

__version__

DEFAULT_BUILD_CONFIG

DEFAULT_EXT_CONFIG

DEFAULT_HTML_CONFIG

DEFAULT_MYST_CONFIG

DEFAULT_CONDITIONAL

DEFAULT_OPTIONAL_EXTENSIONS

DEFAULT_BOOK_THEME_OPTIONS

DEFAULT_THEME_PRIORITY

logger

3.  Classes#

MySTX

mystx 主题注册器：定位主题目录并调用 app.add_html_theme()。

4.  Functions#

config_inited_handler(→ None)

config-inited 事件处理器

build_base_config(→ dict[str, Any])

基于默认字典 + 项目覆盖，组装出 Sphinx 所需的核心配置。

resolve_extensions(, optional, conditional, ...)

解析三类扩展列表（公理 A3 实现）。

register_myst_compat_hooks(→ None)

在 Sphinx app 上统一注册本模块的两个兼容性钩子。

build_minimal_myst_config(→ dict[str, Any])

极简 MyST 预设：仅保留 myst_parser + 两个兼容性钩子。

resolve_theme(, extra_after)

按优先级队列选择第一个已安装的主题（公理 A4 实现）。

resolve_theme_options(→ dict[str, object])

根据选定主题合并默认 theme_options。

deep_merge(→ dict[str, Any])

分层合并配置字典（公理 A1 实现）。

has_module(→ bool)

探测模块是否可导入，不触发模块副作用。

setup(→ sphinx.util.typing.ExtensionMetadata)

Sphinx extension setup.

5.  Package Contents#

mystx.__version__[源代码]#
mystx.config_inited_handler(app: sphinx.application.Sphinx, config: sphinx.config.Config) → None[源代码]#

config-inited 事件处理器

在 Sphinx 完成配置对象（Config）初始化后立即触发，让你有机会在构建器（Builder）创建之前，读取或修改配置。

触发时机:

  • 发生在：conf.py 执行完毕，所有配置变量已收集并封装到 Config 对象中。

  • 早于：builder-inited（构建器初始化）事件。

  • 晚于：扩展加载（extensions 列表中的扩展已导入）。

    • 因为 extensions 已经加载完毕，所以在 config-inited 中修改 extensions 列表不会重新加载扩展。 如果需要动态加载扩展，应使用 app.setup_extension()。

Args:

app: Sphinx应用实例 config: Sphinx配置对象

mystx.DEFAULT_BUILD_CONFIG: dict[str, Any][源代码]#
mystx.DEFAULT_EXT_CONFIG: dict[str, Any][源代码]#
mystx.DEFAULT_HTML_CONFIG: dict[str, Any][源代码]#
mystx.DEFAULT_MYST_CONFIG: dict[str, Any][源代码]#
mystx.build_base_config(params: dict[str, Any] | None = None) → dict[str, Any][源代码]#

基于默认字典 + 项目覆盖，组装出 Sphinx 所需的核心配置。

不包含 extensions / html_theme / hooks（这些在各自模块中处理）。

mystx.DEFAULT_CONDITIONAL: tuple[tuple[str, collections.abc.Callable[[], bool]], ...][源代码]#
mystx.DEFAULT_OPTIONAL_EXTENSIONS: tuple[str, ...] = ('sphinx_design', 'sphinx_copybutton', 'sphinx_tippy', 'sphinx_sitemap',...[源代码]#
mystx.resolve_extensions(required: collections.abc.Sequence[str] = ('myst_parser',), optional: collections.abc.Sequence[str] = (), conditional: collections.abc.Sequence[tuple[str, collections.abc.Callable[[], bool]]] = ()) → list[str][源代码]#

解析三类扩展列表（公理 A3 实现）。

参数：

required: 必须加载的扩展，缺失直接抛 ImportError。 optional: 可选扩展，不存在则静默跳过。 conditional: (ext_name, predicate) 列表——predicate 返回真值才加载；

典型 predicate 如检查 GITHUB_ACTIONS / READTHEDOCS。

返回合并去重后的 extensions 列表（保持首次出现的顺序）。

mystx.register_myst_compat_hooks(app: sphinx.application.Sphinx) → None#

在 Sphinx app 上统一注册本模块的两个兼容性钩子。

mystx.build_minimal_myst_config(override: dict[str, Any] | None = None) → dict[str, Any]#

极简 MyST 预设：仅保留 myst_parser + 两个兼容性钩子。

适用于轻量个人笔记、小型文档站点，不引入任何可选扩展。 override 支持的核心键（与 okf_docs 预设保持字段名一致）：

  • project / author / release / version / language

  • html_title / html_theme / html_theme_options

  • extensions_required / extensions_optional

  • config_override 其余任意 Sphinx 配置覆盖

mystx.DEFAULT_BOOK_THEME_OPTIONS: dict[str, object][源代码]#
mystx.DEFAULT_THEME_PRIORITY: tuple[str, ...] = ('mystx', 'sphinx_book_theme', 'alabaster')[源代码]#
class mystx.MySTX[源代码]#

mystx 主题注册器：定位主题目录并调用 app.add_html_theme()。

Attributes:

app: Sphinx 应用实例，用于注册主题。 name: 主题名称，默认为 "mystx"，对应 theme/<name>/ 子目录。 theme_dir: 解析后的主题目录绝对路径，__post_init__ 中自动设置。

app: sphinx.application.Sphinx#
name: str = 'mystx'#
theme_dir: str | None#
__post_init__() → None[源代码]#
mystx.resolve_theme(priority: collections.abc.Sequence[str] = DEFAULT_THEME_PRIORITY, *, extra_before: collections.abc.Sequence[str] = (), extra_after: collections.abc.Sequence[str] = ()) → str[源代码]#

按优先级队列选择第一个已安装的主题（公理 A4 实现）。

默认回退链：mystx → sphinx_book_theme → alabaster； 其中 alabaster 是 Sphinx 内置主题，保证永不缺失。

参数 extra_before / extra_after 允许在默认队列前后插入自定义主题： extra_before 的项目**优先于**默认主题；extra_after 的项目排在默认 主题之后、alabaster 之前——保证回退到 alabaster 始终是最后一条。

mystx.resolve_theme_options(theme: str, override: dict[str, object] | None = None, *, book_defaults: dict[str, object] = DEFAULT_BOOK_THEME_OPTIONS) → dict[str, object][源代码]#

根据选定主题合并默认 theme_options。

目前对 sphinx_book_theme / mystx 提供完整默认字典； 其他主题返回空字典或 override 原样。

mystx.deep_merge(base: dict[str, Any], override: dict[str, Any] | None = None, *, remove_marker: Any = None) → dict[str, Any][源代码]#

分层合并配置字典（公理 A1 实现）。

规则： * override 中存在的键覆盖 base 同键； * 值为 remove_marker``（默认 ``None）的键**显式表示「从 base 中删除该键」——

注意这与 Sphinx 原生「某键 = None 表示使用 Sphinx 默认」语义不同。 若想表达「将某键显式置为 None 交给 Sphinx 默认处理」，请传 sentinel 对象或其他非 remove_marker 的值；

  • 嵌套字典递归合并，其他类型直接替换。

mystx.has_module(mod: str) → bool[源代码]#

探测模块是否可导入，不触发模块副作用。

等价于原 conf.py 的 _has()，但作为公共 API 导出供外部调用。 基于 importlib.util.find_spec()，比 try-import 更轻量， 不会触发被探测模块的顶层代码执行。

mystx.logger[源代码]#
mystx.setup(app: sphinx.application.Sphinx) → sphinx.util.typing.ExtensionMetadata[源代码]#

Sphinx extension setup.