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
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ jobs:
run: uv sync --only-group dev
- name: Check
run: uv run --no-sync ruff check --output-format=github .
- name: Check docstring coverage
run: uv run --no-sync interrogate src/unilab

ruff-format:
if: github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request'
Expand Down
35 changes: 33 additions & 2 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,10 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
# sphinx-multiversion needs full git refs to build every
# whitelisted branch/tag.
fetch-depth: 0

- name: Install uv
uses: astral-sh/setup-uv@v8.0.0
Expand Down Expand Up @@ -105,9 +109,32 @@ jobs:
echo "::warning::UniLab install failed — deploying prose-only docs"
echo "UNILAB_DOCS_SKIP_AUTODOC=1" >> "$GITHUB_ENV"

- name: Build full HTML
- name: Compute release-line tag whitelist
# Publish the x.y.0 release of every minor line (v1.0.0, v1.1.0,
# v1.2.0, ...) alongside main. New minor releases are picked up
# automatically on the next docs deploy.
run: |
whitelist=$(git tag --list 'v1.*.0' | sort -V | paste -sd'|')
echo "Publishing release lines: $whitelist"
echo "SMV_TAG_WHITELIST=^(${whitelist})$" >> "$GITHUB_ENV"

- name: Build full HTML (all whitelisted versions)
working-directory: docs/sphinx
# sphinx-multiversion builds one subdirectory per whitelisted ref
# (main + the release-line tags computed above; see smv_* in
# source/conf.py). The prose-only fallback still applies —
# UNILAB_DOCS_SKIP_AUTODOC is honoured by conf.py inside each
# per-version build.
run: uv run --no-sync sphinx-multiversion source build/html

- name: Add root redirect
working-directory: docs/sphinx
# Versioned builds land in build/html/<version>/; send / to main.
run: echo '<meta http-equiv="refresh" content="0; url=main/en/0-index.html">' > build/html/index.html

- name: Remove Sphinx doctree caches
working-directory: docs/sphinx
run: uv run --no-sync sphinx-build -j auto -b html -n source build/html
run: find build/html -type d -name .doctrees -exec rm -rf {} +

- name: Push to UniLab-doc gh-pages
uses: peaceiris/actions-gh-pages@v4
Expand All @@ -118,6 +145,10 @@ jobs:
external_repository: unilabsim/UniLab-doc
publish_branch: gh-pages
publish_dir: docs/sphinx/build/html
# Keep files not touched by this deploy: older version directories
# and the pre-existing root-level pages stay reachable, so old
# external links keep working.
keep_files: true
user_name: "github-actions[bot]"
user_email: "github-actions[bot]@users.noreply.github.com"
commit_message: "docs: deploy from UniLab@${{ github.sha }}"
Expand Down
5 changes: 5 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,11 @@ policy. In brief: define a reviewable outcome, choose the PR base before coding,
link the driving issue, validate the final head, and wait for current-head remote
CI only when the PR base is `main`.

New public interfaces must ship with docstrings; CI enforces the interrogate
floor in `pyproject.toml`. PRs with user-visible changes must add an entry to
the `Unreleased` section of `docs/sphinx/source/changelog.md` as described in
`CONTRIBUTING.md`.

When a change crosses runtime, backend, config, registry, or other public
contracts, link the relevant ADR. Add an ADR only for a new structural decision.
Treat new public contracts, lifecycle/protocol changes, routine CI, support
Expand Down
14 changes: 14 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,20 @@ Use Conventional Commits:
- `test:` test-related change
- `chore:` build or tooling

## Changelog Discipline

Every PR with user-visible changes must add an entry to the `## Unreleased`
section at the top of
[docs/sphinx/source/changelog.md](docs/sphinx/source/changelog.md), grouped
under the bilingual subsections `### Added / 新增`, `### Changed / 变更`, or
`### Fixed / 修复` (create the subsection when it is missing). Entries follow
the released-version style below: English prose first, then the Chinese
translation, with the driving GitHub issue or PR linked (for example
`([#706](https://github.com/Motphys/UniLab/issues/706))`). Purely internal
changes (refactors, test-only, or CI plumbing) may skip the changelog. Release
maintainers rename `## Unreleased` to the version number and PyPI upload date
at release time.

## Pull Request Workflow

1. Choose and record the intended PR base before development.
Expand Down
4 changes: 4 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ check: format type check-tests
check-tests:
uv run ruff check tests --select F401,F821,F811,F841 --output-format concise

.PHONY: check-docstrings
check-docstrings:
uv run interrogate src/unilab

.PHONY: test
test:
uv run pytest -m "not slow"
Expand Down
4 changes: 3 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# UniLab Documentation

UniLab 的全部文档源码统一在 [`docs/sphinx/`](sphinx/) 下,通过 Sphinx 构建,部署到
<https://unilabsim.github.io/UniLab-doc/>。
<https://unilabsim.github.io/UniLab-doc/>。站点按版本子路径发布(当前仅 `main/`,
如 `/UniLab-doc/main/en/0-index.html`),根路径自动重定向到 `main/`。

发布入口:

Expand All @@ -20,6 +21,7 @@ UniLab 的全部文档源码统一在 [`docs/sphinx/`](sphinx/) 下,通过 Sphin
| 中文用户指南 | [`docs/sphinx/source/zh_CN/2-user_guide/`](sphinx/source/zh_CN/2-user_guide/) |
| 英文 Developer 指南 | [`docs/sphinx/source/en/4-developer_guide/`](sphinx/source/en/4-developer_guide/) |
| 中文 Developer 指南 | [`docs/sphinx/source/zh_CN/4-developer_guide/`](sphinx/source/zh_CN/4-developer_guide/) |
| How-to 指南(端到端任务演练,中英镜像) | [`docs/sphinx/source/en/6-how_to/`](sphinx/source/en/6-how_to/) |
| 英文 Deployment(sim-to-real / sim-to-sim) | [`docs/sphinx/source/en/3-deployment/`](sphinx/source/en/3-deployment/) |
| 中文 Agent 速查 | [`docs/sphinx/source/zh_CN/4-developer_guide/6-agent_quick_reference.md`](sphinx/source/zh_CN/4-developer_guide/6-agent_quick_reference.md) |
| ADR(共享,中文为主) | [`docs/sphinx/source/adr/`](sphinx/source/adr/) |
Expand Down
8 changes: 7 additions & 1 deletion docs/sphinx/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ source/
├── _static/
└── _templates/
├── sidebar/
│ └── lang_switcher.html # language dropdown in sidebar
│ ├── lang_switcher.html # language dropdown in sidebar
│ └── versioning.html # version dropdown (rendered only under sphinx-multiversion)
└── autosummary/
```

Expand All @@ -48,6 +49,11 @@ language. The language switcher uses an explicit path map in `conf.py`
page, add a corresponding entry to that map** so the switcher lands somewhere
sensible (or omit the entry to fall back to the zh_CN index).

Top-level numbered sections run `1-getting_started` through `6-how_to/`;
`6-how_to/` is the home of user-facing, end-to-end task walkthroughs whose
every step carries a verification command (the en/zh_CN trees mirror it 1:1,
so its pages need no `_LANGUAGE_PATH_FORWARD` entries).

Do not add per-page language button blocks or hand-written cross-language
navigation. The sidebar language switcher handles language changes globally.

Expand Down
39 changes: 31 additions & 8 deletions docs/sphinx/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,10 @@
UniLab 的文档源码全部在这里,**双语平行结构**——`source/en/` 是英文版,`source/zh_CN/`
是中文版,`adr/`、`api_reference/`、`glossary.md`、`changelog.md`、`_static/` 共享。

CI 在 push to `main` 时构建 Sphinx,通过 deploy key 推到独立仓
CI 在 push to `main` 时用 sphinx-multiversion 构建 Sphinx,通过 deploy key 推到独立仓
[`unilabsim/UniLab-doc`](https://github.com/unilabsim/UniLab-doc) 的 `gh-pages` 分支,
由 GitHub Pages 发布到 <https://unilabsim.github.io/UniLab-doc/>。
由 GitHub Pages 发布到 <https://unilabsim.github.io/UniLab-doc/>。站点按版本目录发布
(当前仅 `main/`),根路径重定向到 `main/`。

## 目录结构

Expand Down Expand Up @@ -41,7 +42,9 @@ docs/sphinx/
└── agents/ ← Agent 速查(中文,01-agent-quick-reference.md)
```

URL 模式:`/`(语言 picker)、`/en/...`、`/zh_CN/...`。两种语言路径 1:1 镜像。
URL 模式:`/`(重定向到 `main/en/0-index.html`)、`/main/en/...`、`/main/zh_CN/...`;
历史大版本在 `/<tag>/en/...`(如 `/v1.5.11/en/...`)。站点按
版本目录发布,版本目录内两种语言路径 1:1 镜像。

## 本地构建

Expand Down Expand Up @@ -73,7 +76,8 @@ UNILAB_DOCS_SKIP_AUTODOC=1 uv run --no-project --with-requirements requirements.

CI 工作流在 `.github/workflows/docs.yml`:

- **PR**: prose-only HTML build,跳过 API reference,failed 阻塞 PR
- **PR**: prose-only HTML build(plain `sphinx-build`),跳过 API reference,
failed 阻塞 PR。plain build 下 `versions` 上下文不存在,侧栏版本切换器不渲染
- **push to main**: prose-only build 通过后,`deploy` job 执行完整构建(安装
UniLab + autodoc)并通过 deploy key(`UNILAB_DOC_DEPLOY_KEY` secret)推送到
[`unilabsim/UniLab-doc`](https://github.com/unilabsim/UniLab-doc) 的
Expand All @@ -82,6 +86,20 @@ CI 工作流在 `.github/workflows/docs.yml`:
- **手动**: `workflow_dispatch` 在 `main` 上触发时走同一套构建 + 部署;
在其他分支触发时只做 prose-only build

deploy job 用 `sphinx-multiversion source build/html` 构建,按版本目录发布:
每个白名单 ref 构建到 `build/html/<version>/`,随后在 `build/html/index.html` 写入根
redirect(`meta refresh` → `main/en/0-index.html`),再清理各版本目录下的
`.doctrees` 缓存后发布。发布步骤带 `keep_files: true`,旧版本目录和存量根目录
页面不会被覆盖删除,旧外链保持可用。

发布的版本集合:`main` 分支(`smv_branch_whitelist = ^(main)$`)+ 每条 minor
发布线的 `x.y.0` 版本(v1.0.0、v1.1.0、v1.2.0、v1.3.0、v1.4.0、v1.5.0……)。
tag 白名单由 deploy job 的 "Compute release-line tag whitelist" 步骤从 git tag
动态计算并经 `SMV_TAG_WHITELIST` 注入,新 minor 版本在下次部署时自动出现,无需改
配置。本地构建默认只构建 `main`(`smv_tag_whitelist = ^$`);要复现全量版本,
自行导出同名环境变量即可。每个版本的 `html_baseurl` 由 conf.py 的
`_versioned_html_baseurl` 按 `smv_current_version` 动态设置,sitemap 各自正确。

PR 与 push 的检查性构建明确设置 `UNILAB_DOCS_SKIP_AUTODOC=1`,不安装 UniLab
运行时依赖,也不跑 linkcheck。下面的本地发布流程保留为 CI 部署不可用时的
fallback。
Expand All @@ -97,14 +115,18 @@ fallback。
### 本地发布到 UniLab-doc

完整 API 文档在本地构建完成后,把 `docs/sphinx/build/html/` 的内容同步到
`unilabsim/UniLab-doc` 的 `gh-pages` 分支根目录:
`unilabsim/UniLab-doc` 的 `gh-pages` 分支根目录。构建方式与 CI 一致,用
sphinx-multiversion(需要本地有对应 git ref;`main` 分支存在即可,shallow clone
也能构建),构建后补写根 redirect 并清理 `.doctrees`:

```bash
# 在 UniLab 仓库根目录
uv sync
uv pip install -r docs/sphinx/requirements.txt
cd docs/sphinx
uv run --no-sync sphinx-build -j auto -b html -n source build/html
uv run --no-sync sphinx-multiversion source build/html
echo '<meta http-equiv="refresh" content="0; url=main/en/0-index.html">' > build/html/index.html
find build/html -type d -name .doctrees -exec rm -rf {} +
cd ../..
```

Expand All @@ -121,10 +143,11 @@ git -C ../UniLab-doc checkout gh-pages
git -C ../UniLab-doc pull --ff-only
```

同步构建产物并推送:
同步构建产物并推送。**不要加 `--delete`**:CI 发布用 `keep_files: true` 保留旧版本
目录和存量根目录页面,本地手动发布也要保留它们:

```bash
rsync -a --delete --exclude .git docs/sphinx/build/html/ ../UniLab-doc/
rsync -a --exclude .git docs/sphinx/build/html/ ../UniLab-doc/
touch ../UniLab-doc/.nojekyll

SOURCE_SHA=$(git rev-parse --short HEAD)
Expand Down
2 changes: 2 additions & 0 deletions docs/sphinx/requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,5 @@ sphinxcontrib-mermaid>=0.9
sphinx-togglebutton>=0.3
linkify-it-py>=2.0
sphinx-sitemap>=2.6
sphinx-multiversion>=0.2
beautifulsoup4>=4.12
29 changes: 29 additions & 0 deletions docs/sphinx/source/_static/css/custom.css
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,35 @@ kbd {
border-color: var(--color-brand-primary);
}

/* ---------- Sidebar version switcher (sphinx-multiversion) ---------- */
.sidebar-version-switcher {
display: flex;
align-items: center;
gap: 0.5rem;
padding: 0.4rem 0.8rem;
margin: 0 0 0.2rem 0;
}
.sidebar-version-label {
color: var(--color-foreground-secondary);
font-size: 0.85rem;
font-weight: 600;
}
.sidebar-version-select {
flex: 1;
min-width: 0;
padding: 0.35rem 0.6rem;
font-size: 0.85rem;
border: 1px solid var(--color-foreground-border);
border-radius: 6px;
background: var(--color-background-secondary);
color: var(--color-foreground-primary);
cursor: pointer;
appearance: auto;
}
.sidebar-version-select:hover {
border-color: var(--color-brand-primary);
}

/* Hide old body-injected language switcher */
.language-switcher { display: none !important; }
.landing-language-picker { display: none !important; }
17 changes: 17 additions & 0 deletions docs/sphinx/source/_templates/sidebar/versioning.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
{# Furo sidebar component: version switcher (sphinx-multiversion).
Renders only under `sphinx-multiversion` builds, which inject `versions`
and `current_version` into the HTML context; plain `sphinx-build` runs
leave `versions` undefined and the guard hides the switcher. #}
{% if versions %}
<div class="sidebar-version-switcher">
<label class="sidebar-version-label" for="version-select">Version</label>
<select id="version-select" class="sidebar-version-select" onchange="location = this.value;">
{%- for item in versions.branches %}
<option value="{{ item.url }}" {% if item == current_version %}selected{% endif %}>{{ item.name }}</option>
{%- endfor %}
{%- for item in versions.tags|reverse %}
<option value="{{ item.url }}" {% if item == current_version %}selected{% endif %}>{{ item.name }}</option>
{%- endfor %}
</select>
</div>
{% endif %}
Loading
Loading