Skip to content

Document reading a weather file, once, for both languages - #11

Draft
samuelduchesne wants to merge 1 commit into
007-climate-zone-filterfrom
007-weather-file-readers
Draft

Document reading a weather file, once, for both languages#11
samuelduchesne wants to merge 1 commit into
007-climate-zone-filterfrom
007-weather-file-readers

Conversation

@samuelduchesne

Copy link
Copy Markdown
Contributor

One page, prose written once, code varying by language, filed as a how-to beside its siblings in weather/. Nothing about reading an EPW differs between the two libraries in a way that needs different explanation: the retrieval before it does, and the page says so and links to where that is explained.

Stacked on #10, which carries the climate-zone snippet. Base it on main once that merges.

Draft, and red on purpose. The build fails on exactly three things and nothing else, all of them pins rather than prose:

  1. parity("weather-file-reading") does not resolve at governance-2026.14. The row is in idfkit-conformance#8.
  2. docs/snippets/js/weather/reading/{read_an_epw,absent_values}.ts are not in docs-2026.3. They are authored in idfkit-js#55, because docs/snippets/js/ is vendored and sync_js_artifacts.py --check rejects a file present only in the vendored copy.
  3. The Python snippets call parse_epw and monthly_means, which idfkit==1.0.0-rc.3 does not have. They are in idfkit#204.

All three clear with one pin bump after the two libraries release — the same bump #10 is already waiting on. Verified locally with both documented overrides (sync_js_artifacts.py --from-sibling and IDFKIT_GOVERNANCE_DIR): the page renders with no ERROR, both language tabs, and the parity block.

What the page does

  • States the hour convention once, because hour 24 is the last hour of its own day and a chart that assumes otherwise is off by one for every day of the year and looks right until somebody checks a value.
  • Explains that a measurement the file says was not taken is absent rather than the number the format reserves for it, and why ceiling height's 77777 is an observation that stays a number where 99999 is not.
  • Says the monthly mean excludes absent hours from the sum and from the divisor, and why the count is part of the answer.

It records a decision where a reader would look for it

FR-024: there is no public summary reader, and the page says so rather than leaving a reader to conclude it was overlooked. The .stat member is a report written for a person, in around forty section shapes whose set varies with the station's climate, and every figure in it is derivable from the EPW itself. It is read in exactly one place — as the conformance corpus's oracle — where a brittle parse is an offline maintenance task rather than something in a caller's path.

Checks

check-page-kinds and check-capabilities both pass. The 109 cairosvg warnings in a local strict build are the social plugin wanting libcairo on this machine and are identical with and without this change.

One page, prose written once, code varying by language, filed as a how-to beside
its siblings in `weather/`. Nothing about reading an EPW differs between the two
libraries in a way that needs different explanation: the retrieval before it does,
and the page says so and links to where that is explained.

It declares `weather-file-reading` through the parity macro, so the build fails if
the capability resolves to nothing.

It records the decision against a public summary reader where a reader would look
for one, rather than leaving them to conclude it was overlooked: the `.stat` member
is a report written for a person, in around forty section shapes whose set varies
with the station's climate, every figure of which is derivable from the EPW itself.
It is read in one place, as the conformance corpus's oracle, where a brittle parse
is an offline maintenance task rather than something in a caller's path.

BLOCKED UNTIL THE PINS MOVE, on exactly three things and nothing else: the parity
macro cannot resolve `weather-file-reading` at governance-2026.14, the vendored
TypeScript snippets are not in docs-2026.3, and the Python snippets call functions
idfkit==1.0.0-rc.3 does not have. All three clear with the pin bump that follows the
release, which is where `weather/station-search.md` is already waiting.
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.

1 participant