Skip to content

feat: single-source config docs generated from YAML seeds (#2107) - #2114

Merged
ranxianglei merged 1 commit into
masterfrom
2026-10-04_config-docs-gen
Oct 4, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-10-04_config-docs-gen

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 4, 2026 •

Copy link
Copy Markdown
Owner

Closes #2107

What

#2052's audit exposed the structural gap: website /docs/ config references were hand-transcribed snapshots with no pipeline to src/ + CONFIGURATION.md. This PR makes the config docs a single source of truth — humans write one place, both artifacts (repo manual + site) stay consistent, drift is blocked at PR merge time.

website/config-reference/*.yaml   <- ONLY hand-maintained reference (7 domain files, 225 entries)
        | tools/gen-config-docs.mjs (pure Node, zero deps)
        |---> CONFIGURATION.md / CONFIGURATION.zh-CN.md marked blocks (Parameter Reference index + env-knob map tables)
        +---> website/main.js i18n dict segments + website/docs/index.html table rows (inline EN no-JS fallback)

Generated artifacts are committed inside <!-- bili:gen id --> / /* bili:gen */ marker blocks; human prose outside blocks is byte-untouched. Site stays pure static — pages.yml untouched, no build step added.

Drift guards (two new jobs in existing ci.yml)

  • docs-sync: regenerate + git diff --exit-code on the four artifact files — schema edited without re-running the generator goes red.
  • docs-coverage: every BILI_*/ACP_* env var read in src/ (direct reads, bracket reads, alias-param reads, helper-call literals incl. second-arg forms) and every FileConfig top-level key must have a seed entry — undocumented param goes red with the missing names listed.

Acceptance evidence (all verified locally on the committed state)

  • Idempotent: double run byte-identical (md5-checked)
  • Wrong default -> docs-sync-style diff readable (port 8787->9999 shows in both index and env-map rows)
  • Deleted env entry -> coverage red exit 1 naming BILI_STREAM_STALL_MS
  • EN/ZH dict cross-check: 206 keys, sets equal, every data-i18n(-html) ref resolves (built into generate)
  • Subpath mount (/billion-context/) serves all local assets 200
  • Pages deploy parity: nothing is injected at deploy time (no build), so repo files ARE the deploy artifacts — confirmed by construction

Behavior changes (docs-only; NO config surface added, no runtime change)

  • Env-map table rows now sorted alphabetically by env name (was subsystem-grouped); zh Default column normalized to the shared value strings.
  • cr.models / cr.compat site cells switch data-i18n -> data-i18n-html: their dict values contain <span class='mech'> markup that previously rendered as RAW TEXT in the browser (pre-existing defect, fixed mechanically by the generator).
  • Parameter Reference section gains its first content (was an empty status-legend stub).

Note on an in-passing fix (#2064 shipped it first)

While working this I found releaseNotesCheck/releaseNotesUrl declared in FileConfig and read by loadOptions but missing from KNOWN_TOP_LEVEL_KEYS — users setting either got a spurious "ignoring unknown top-level config key" warning although the value applied. I committed the one-line Set fix; after rebasing onto current master it became a no-op because #2064 had already added both keys to the Set (the rebase dropped my duplicate commit). The branch therefore carries only the docs-generation commit; nothing further needed on that front.

website/config-reference/*.yaml (7 domain files, 225 entries) become the ONLY hand-maintained config reference. tools/gen-config-docs.mjs (pure Node, zero deps) regenerates, inside <!-- bili:gen --> / /* bili:gen */ marker blocks: the Parameter Reference index + env-knob map tables in CONFIGURATION.md/.zh-CN.md, and the i18n dict segments in website/main.js plus the table rows in website/docs/index.html (with inline EN no-JS fallback). Generated artifacts are committed; pages.yml untouched (site stays static, zero build step).

CI gains two guard jobs: docs-sync (regenerate + git diff --exit-code on the four artifact files) and docs-coverage (every BILI_*/ACP_* env var read in src/ and every FileConfig top-level key must have a seed entry; missing names listed, exit 1).

Acceptance verified locally: double-run byte-identical; wrong default -> readable diff; deleted env entry -> coverage red naming it; EN/ZH dict sets equal with all refs resolving; subpath mount serves all local assets 200.

Behavior changes (docs-only, no config surface added): env-map table rows now sorted by env name (was subsystem-grouped) and zh defaults normalized to the shared value strings; cr.models/cr.compat site cells switch data-i18n -> data-i18n-html because their values contain <span class='mech'> markup that previously rendered as raw text; Parameter Reference section gains its first content (previously an empty legend stub); human prose outside marker blocks is byte-untouched.
@ranxianglei
ranxianglei force-pushed the 2026-10-04_config-docs-gen branch from 5e26b95 to 19bb01a Compare October 4, 2026 15:39
@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-04_config-docs-gen (19bb01a)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2162-pr.2114.d4143a4

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr2114.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei
ranxianglei merged commit 5e43209 into master Oct 4, 2026
17 checks passed
@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.23-master.5e43209 (rolling master tag).

npm install -g billion-context@0.0.23-master.5e43209  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

@ranxianglei
ranxianglei deleted the 2026-10-04_config-docs-gen branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[docs][website] 配置文档单一事实源:从声明式 schema 生成 CONFIGURATION.md 与网站 /docs/(一步到位)

1 participant