Document the seven ways the two writers disagree - #1
Merged
Conversation
The parity record carried these in its differences field while write was partial on both sides. Feature 002 closed the five controls, so the entry is complete, and the gate does not keep a differences field on a capability that is complete: a reader would have no way to tell a difference that still matters from one that was left behind. So they come here. If this page goes away the information exists nowhere, and the record says so at the point it stopped carrying them. The measurement is stated rather than asserted, and was re-taken the day the entry closed: 5ZoneAirCooled.idf from EnergyPlus 26.1.0, 359 objects, 4,031 lines against 4,125. A reader can re-derive it in three lines. The page says plainly that neither writer is more correct, that both are published, that byte-identical output across the two languages is not promised and is not coming, and that the thing to do instead is pass EnergyPlus the model rather than diff two outputs. The Python examples run from docs/snippets. The TypeScript ones are referenced at the vendored path every other page uses; the snippet itself lives in idfkit-js and reaches this repository through a docs release, so the TypeScript half of this page renders once that release is cut.
The how-to opened by explaining that the two libraries report recoverable findings differently and that the difference was idiomatic. That was true and is not any more: both hand the findings back beside the document now, in one call, with nothing to configure first. The logging path keeps its own section rather than being deleted, because it still works, still fires every record it did, and is still the better choice for watching a long batch go by. What it is no longer is the only way in. The logging concept page gains the same note from the other end, with a table saying which of the two to reach for, and a reminder that everything which is not a parse finding, the timings and the mmap notices and the simulation records, is still reachable only through logging.
The page included a vendored TypeScript snippet that does not exist yet, and pymdownx.snippets runs with check_paths: true, so mkdocs build aborted with SnippetMissingError and produced no site at all. Not a missing tab on one page: the whole build. The snippet lives in idfkit-js and reaches this repository through a docs release, which has not been cut. The includes are removed and the page says so in prose, so it builds now and gains its TypeScript examples when the release lands. The page also claimed five controls exist on both writers. Three do; ordering and versionFirst are each spelled on one side only, and the page now names them.
The page said five controls were closed and two were still spelled on one side only. Both have been added since, so the claim is replaced with a table naming each control in each language and the defaults that still differ, which is the distinction the page exists to make: a control lets you ask for the other behaviour, it does not change what you get by asking for nothing. The Python example gains version_first, so every control on the page appears in a snippet that runs.
The site states the level to the reader, so it moves with the libraries.
deploy-pr-docs.yml called the shared setup action with no version, so it got the action's 3.10 default against a project requiring >=3.12 and failed at dependency resolution before reaching a single page. docs.yml has always passed 3.12 explicitly; this workflow never did, and has no successful run in its history. Pre-existing and unrelated to feature 002, but it is the only red check left on the site's pull request.
Contributor
|
Docs preview for this PR is available at: Changed pages: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Feature 002, the site half.
Depends on idfkit/idfkit-conformance#1. This bumps the governance pin to
governance-2026.10and the conformance pin toconformance-2026.8, neither of which exists until that merges and the tags are cut, so the build is red until then.Why a new page exists
The parity record carried the seven measured default-output differences in the
writeentry'sdifferencesfield while the capability was partial on both sides. Feature 002 closed the five controls, so the entry iscomplete, and the gate does not keep adifferencesfield on a capability that is complete: a reader would have no way to tell a difference that still matters from one that was left behind.So they come here. If this page goes away the information exists nowhere, and the record says so at the point it stopped carrying them.
The measurement is stated rather than asserted, and was re-taken the day the entry closed:
5ZoneAirCooled.idffrom EnergyPlus 26.1.0, 359 objects, 4,031 lines against 4,125. A reader can re-derive it in three lines.The page says plainly that neither writer is more correct, that both are published, that byte-identical output across the two languages is not promised and is not coming, and that the thing to do instead is pass EnergyPlus the model rather than diff two outputs.
Two how-to pages catch up
collect-diagnostics.mdopened by explaining that the two libraries report recoverable findings differently and that the difference was idiomatic. That was true and is not any more: both hand the findings back beside the document now, in one call, with nothing to configure first. The logging path keeps its own section rather than being deleted, because it still works and is still the better choice for watching a long batch go by.concepts/logging.mdgains the same note from the other end, with a table saying which of the two to reach for.One known gap on the new page
It has no TypeScript example.
pymdownx.snippetsruns withcheck_paths: true, anddocs/snippets/js/is vendored wholesale from an idfkit-js docs release and must match the pinneddocs-2026.1exactly, so a snippet authored here fails the vendored-artifact gate and a snippet referenced but absent aborts every build.The file waits at
docs-snippets/explanation/two-writers-one-model/controls.tsin idfkit-js, where it type-checks. The page gains its TypeScript half when a docs release carries it andscripts/sync_js_artifacts.pyvendors it.Constitution VI asks for executable examples in both languages, so this page does not satisfy it yet. Flagging rather than burying it.
A second gap, and it needs a release
The Python snippet exercises every writer control, including the three added in feature 002. This repository pins
idfkit==0.15.0, whose signature predates them, souv run pyright docs/snippets/reportsNo overloads for "write_idf" match the provided arguments.Clearing it needs an idfkit release and a bump of both
idfkit==and[tool.idfkit.library]. Adding apyright: ignorewould defeat the gate that exists to catch exactly this drift.Verification
mkdocs buildexits 0. The page-kind, capability, engine-bytes and vendored-artifact gates all pass.make checkstill fails on a pre-existingS310inscripts/sync_js_artifacts.py, untouched here.