维护者说明
API 页面
tools/generate_api_pages.py 依据已提交的符号清单重建 docs/site/api/<module>.md：每个顶层声明一条 Breathe 指令，重载函数按完整签名输出，模板函数按名称输出，多行字符串常量则列在脚本的 UNRENDERABLE 集合中。请修改清单输入而不是生成的页面；脚本是确定性的，因此一轮已审阅的改动只会体现为很小的 diff。
Doxygen 会在 <argsstring> 中输出 C++14 数字分隔符，而 Sphinx C++ 域无法解析，因此必须在 doxygen 与 sphinx-build 之间运行 tools/normalize_doxygen_xml.py。.readthedocs.yaml 与 docs 工作流都已如此做；本地构建步骤为：
cd docs/site
mkdir -p ../_build/doxygen # Doxygen creates one level only
doxygen Doxyfile
python tools/normalize_doxygen_xml.py ../_build/doxygen/xml
python tools/build_api_ledger.py
python tools/generate_api_pages.py
翻译
cd docs/site
sphinx-build -b gettext -W --keep-going . ../_build/gettext
sphinx-intl update -p ../_build/gettext -l zh_CN
# edit locale/zh_CN/LC_MESSAGES/*.po and clear fuzzy entries
FINCORE_DOCS_LANGUAGE=zh_CN sphinx-build -b html -W -n --keep-going . ../_build/html/zh_CN
tools/apply_translations.py <catalog> <json> 按 msgid 到 msgstr 的 JSON 映射填充目录，使批量翻译保持可审阅，并避免手工处理换行。提交前先核对总数：
msgfmt --statistics -o /dev/null locale/zh_CN/LC_MESSAGES/**/*.po
未翻译集合必须恰好等于 docs/iterations/iteration-10-comments-bilingual-docs/exemptions.md 中经审阅的标识符豁免；任何其它未翻译条目都会阻止双语发布。
保留标识符、命令、路径、公式和代码块的字面形式。术语表使用 returns=收益率、drawdown=回撤、volatility=波动率、horizon=预测期、turnover=换手率、exposure=暴露、annualization=年化。
由于引用节点无法在 gettext 中保留（译文段落丢掉引用就会让严格构建失败），Doxygen 自动链接已被关闭（AUTOLINK_SUPPORT = NO）。请改为在叙述页面中显式书写交叉引用。
生成的产物
docs/_build/（Doxygen XML、gettext 模板、.mo、HTML）已被忽略。docs/site/locale/**/LC_MESSAGES/*.po 和 api-ledger*.{tsv,json} 是源产物，变更时应提交。
注释轮次
使用
tools/build_api_ledger.py冻结公共符号清单。一次只编辑一个模块的公共头文件；使用
///编写 Google 风格契约，使用///<简要说明字段/枚举值。不要改变代码或格式。对涉及的头文件运行
tools/check_comment_only.py。重新生成 Doxygen XML 和符号清单；记录已说明/缺失数量。
运行相关测试（发布候选需运行完整测试套件）。
使用
-W -n --keep-going构建两种语言的站点。更新英文页面、
.po翻译、页面清单和源码链接；只提交已审阅的轮次。