diff --git a/docs/sphinx/README.md b/docs/sphinx/README.md index a52497c43..616e1e194 100644 --- a/docs/sphinx/README.md +++ b/docs/sphinx/README.md @@ -82,7 +82,8 @@ CI 工作流在 `.github/workflows/docs.yml`: UniLab + autodoc)并通过 deploy key(`UNILAB_DOC_DEPLOY_KEY` secret)推送到 [`unilabsim/UniLab-doc`](https://github.com/unilabsim/UniLab-doc) 的 `gh-pages` 分支,GitHub Pages 自动更新站点。完整构建安装失败时降级为 - prose-only 构建并仍然部署 + prose-only 构建并仍然部署。历史 tag 版本始终为 prose-only(autodoc 只能 + 反映当前安装的代码,给旧版本生成 API 文档既会失败也不正确) - **手动**: `workflow_dispatch` 在 `main` 上触发时走同一套构建 + 部署; 在其他分支触发时只做 prose-only build diff --git a/docs/sphinx/source/changelog.md b/docs/sphinx/source/changelog.md index 05cd6a073..582c33267 100644 --- a/docs/sphinx/source/changelog.md +++ b/docs/sphinx/source/changelog.md @@ -96,6 +96,11 @@ PyPI 版本变更与未发布变更;发布日期采用 PyPI 上传日期。完 ### Fixed / 修复 +- The docs deploy build now builds historical tags prose-only: autodoc can + only document the installed (current) package, so generating the API + reference for tags failed on modules removed since those releases. + 文档部署构建对历史 tag 版本改用 prose-only:autodoc 只能反映当前安装的 + 代码,为 tag 版本生成 API 参考会因已移除模块而失败。 - Documentation corrections verified by smoke-running the documented commands on 1.5.9: training requires the `unirl` extra (install/quick-start/CLI pages previously omitted it); run log directories use the registry task name; the diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index b3c6fca03..a60245b86 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -454,19 +454,26 @@ def _inject_language_sidebar_navigation( # Expose `_UNILAB_AVAILABLE` as a Sphinx tag so `.. only:: api_ref` blocks # in prose can be conditionally rendered. def setup(app): - if _UNILAB_AVAILABLE: - app.tags.add("api_ref") - else: - app.tags.add("prose_only") - app.connect("config-inited", _versioned_html_baseurl) + app.connect("config-inited", _apply_per_version_overrides) app.connect("html-page-context", _inject_language_switcher) app.connect("html-page-context", _inject_language_sidebar_navigation, priority=700) -def _versioned_html_baseurl(app, config): - # sphinx-multiversion builds every whitelisted ref with this same conf.py; - # point each version's canonical URLs (sitemap etc.) at its own subdir. +def _apply_per_version_overrides(app, config): + # sphinx-multiversion builds every whitelisted ref with this same conf.py. current = getattr(config, "smv_current_version", "") + historical = bool(current) and current != "main" + # autodoc can only document the *installed* package, which is always the + # checkout being deployed. Generating API reference for historical tags + # would therefore fail on removed modules (and misdescribe the old API + # even when imports happen to resolve), so tags build prose-only. + if _UNILAB_AVAILABLE and not historical: + app.tags.add("api_ref") + else: + app.tags.add("prose_only") if current: config.html_baseurl = f"https://unilabsim.github.io/UniLab-doc/{current}/" + if historical: + config.exclude_patterns.append("api_reference/**") + config.autosummary_generate = False return {"parallel_read_safe": True}