What is not finished

The two libraries now share a vocabulary, a conformance corpus, a parity ledger and a documentation site. Several things were deliberately not closed along the way. This page is the list, so that none of them is discovered as a surprise.

Two other pages cover neighbouring ground and are not repeated here. Capability parity lists every capability and its state in each language. How conformance is established covers what the corpus does and does not prove about agreement.

The second and third tiers stay single-language

First-tier capabilities exist in both languages: parsing, the object model, references, writers, schema access, validation, introspection, documentation addresses, generated object types, parse diagnostics, the weather station index, weather file retrieval, and geocoding.

Everything above that tier is Python-only, and that was the plan rather than the remainder. Geometry authoring, surface matching, zoning, thermal properties, schedule evaluation, output-variable selection, design-day sizing, version migration, the command line, schema compatibility checking and result plotting are roughly ten times the work of the first tier, and porting them without first fixing the shared vocabulary would have meant renaming them afterwards.

They are on the ledger as absent with absence_kind = "not-yet" and a tracking issue each, which is the difference between a gap and an omission. A few capabilities are never instead, and those are permanent: driving a locally installed EnergyPlus needs a subprocess a browser does not have, and running EnergyPlus in a browser needs a WebAssembly build Python has no use for. Neither is a deficiency in the other language.

The TypeScript reference needs a shim, and will for a while

The TypeScript half of the API reference is generated by TypeDoc in idfkit-js, published as a pinned artifact, and rendered here through mkdocstrings-typescript. Two things about that toolchain are worked around rather than solved, both in docs/hooks/typedoc_shim.py:

griffe-typedoc is described by its own author as a prototype, and its model was written against an earlier TypeDoc. It decodes strictly, so current TypeDoc output kills the build on the first unmodelled key or type kind. The shim coerces what it cannot model and drops keys nothing renders. The alternative was pinning TypeDoc, and with it TypeScript, which the packages track closely.

mkdocstrings-typescript also regenerates the JSON by shelling out to a typedoc executable on every build, with no option to hand it a file. This site must build with no Node toolchain, so the shim replaces that call with a read of the pinned artifact.

Both go away when the upstream tools catch up. The signal that the first one has started costing something is the reference losing detail: a type rendered as M[K] rather than as a cross-linked structure is the shim doing its job.

The live runner is not verified by CI

The browser-simulation how-to embeds a runner that downloads a WebAssembly EnergyPlus and executes it in the reader's tab. It runs the same file CI type-checks, so a renamed engine method breaks the documentation checks.

Nothing in CI runs EnergyPlus in a browser. A change that type-checks and produces wrong output would ship, and the reader pressing the button is the only thing that would notice. That is why the page calls it a demonstration and this site does not present it as evidence.

The site will move, and it is built so that moving is a move

The documentation lives in the idfkit repository today, which is convenient while the Python library is the larger of the two and inconvenient afterwards: one library's repository hosting the site that teaches both invites its pages to drift towards that library.

It is meant to become idfkit/idfkit-developers, with idfkit a pinned PyPI dependency of the site build in exactly the way the TypeDoc artifact is already a pinned dependency of it. The extraction is out of scope for this work, and nothing here waits on it.

What makes it a move rather than a rewrite is a build check that already runs. The portable job copies docs/ and mkdocs.yml to a scratch directory outside the repository, installs idfkit from a built wheel rather than resolving it out of src/, and runs the same strict build there. An include, a hook path or a template directory that reaches outside the documentation tree fails on the day it is introduced instead of on extraction day. It found one such coupling already and it is empty now.

So the remaining work is a git mv, a repository, and deleting one line of paths: from mkdocs.yml.