Skip to content

Adopt docs-2026.2, and take the language service's examples from it - #5

Merged
samuelduchesne merged 1 commit into
mainfrom
007-vendor-docs-2026-2
Sep 5, 2026
Merged

Adopt docs-2026.2, and take the language service's examples from it#5
samuelduchesne merged 1 commit into
mainfrom
007-vendor-docs-2026-2

Conversation

@samuelduchesne

Copy link
Copy Markdown
Contributor

Closes T015.

The gap

The two TypeScript examples on the language service page were authored here, where nothing checks them. This repository checks Python with pyright, and the one TypeScript tree it does check, docs/snippets/js/, is vendored byte for byte from a docs-YYYY.N release of idfkit-js and is never hand-edited.

So a rename in @idfkit/language would have left the published page showing code that compiles in nobody's checkout, and a reader would have found out first.

What changes

idfkit-js#43 moved them into docs-snippets/, where tsconfig.docs.json compiles them against the published surface rather than the sources. docs-2026.2 ships them. This vendors that release and repoints the page's eight includes:

docs/snippets/explanation/idf_language_service.ts
-> docs/snippets/js/explanation/idf-language-service/the_five_answers.ts
docs/snippets/explanation/idf_language_service_translation.ts
-> docs/snippets/js/explanation/idf-language-service/translating_to_a_protocol.ts

The hand-authored copies are deleted rather than left to rot beside the checked ones.

Verified, not assumed

  • All four regions each file needs are present in the vendored copy.
  • The strict build renders eight code blocks, none empty — a wrong region name would have produced silence rather than an error.
  • sync_js_artifacts.py --check confirms the tree matches docs-2026.2.
  • check_page_kinds.py and check_capability_declarations.py both pass.

Also in this diff

docs/snippets/js/explanation/two-writers-one-model/controls.ts, added to idfkit-js after docs-2026.1, and a refreshed typedoc.json. Both arrive because the reference and the examples are pinned on one tag, so they always describe the same commit.

Levels

[tool.idfkit.docs] moves to docs-2026.2. The conformance, governance and library levels do not.

Pre-existing, unrelated

make check is red on main too: ruff reports S310 in scripts/sync_js_artifacts.py, untouched here. And [tool.idfkit.library] is still 0.15.0, which lacks names its own merged pages document.

Closes T015. The two TypeScript examples on the language service page were
authored here, where nothing checks them: this repository checks Python with
pyright, and the one TypeScript tree it does check, docs/snippets/js/, is
vendored byte for byte from a docs-YYYY.N release of idfkit-js and is never
hand-edited. A rename in @idfkit/language would have left the published page
showing code that compiles in nobody's checkout, and a reader would have found
out first.
They now come from the release, like every other TypeScript example on the
site. idfkit-js#43 moved them into docs-snippets/, where tsconfig.docs.json
compiles them against the published surface; docs-2026.2 ships them. The page's
eight include paths move from docs/snippets/explanation/ to
docs/snippets/js/explanation/idf-language-service/, and the hand-authored copies
are deleted rather than left to rot beside the checked ones.
Verified rather than assumed: all four regions each file needs are present in
the vendored copy, the strict build renders eight code blocks and none of them
is empty, and sync_js_artifacts.py --check confirms the tree matches
docs-2026.2.
Also arriving with the newer artifact: docs/snippets/js/explanation/
two-writers-one-model/controls.ts, added to idfkit-js after docs-2026.1, and a
refreshed typedoc.json. Both are what pinning one tag for the reference and the
examples together is for, so the two always describe the same commit.
[tool.idfkit.docs] moves to docs-2026.2. The conformance, governance and library
levels do not.
@github-actions

Copy link
Copy Markdown
Contributor

github-actionsBot added a commit that referenced this pull request Sep 5, 2026
@samuelduchesne
samuelduchesne merged commit b85789c into mainSep 5, 2026
6 checks passed
github-actionsBot added a commit that referenced this pull request Sep 5, 2026
Sign up for freeto 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.

1 participant

@samuelduchesne