Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/sphinx/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
5 changes: 5 additions & 0 deletions docs/sphinx/source/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
23 changes: 15 additions & 8 deletions docs/sphinx/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Loading