Skip to content

feat: add clickable BigLadder doc links to Inspector and SimSettings headers#876

Open
Ski90Moo wants to merge 1 commit into
openstudiocoalition:developfrom
Ski90Moo:feat/doc-links-inspector
Open

feat: add clickable BigLadder doc links to Inspector and SimSettings headers#876
Ski90Moo wants to merge 1 commit into
openstudiocoalition:developfrom
Ski90Moo:feat/doc-links-inspector

Conversation

@Ski90Moo
Copy link
Copy Markdown

@Ski90Moo Ski90Moo commented May 24, 2026

Summary

Implements the enhancement requested in #160 — adds clickable hyperlinks from IDD type headers and Simulation Settings section headers to the relevant EnergyPlus 25.1 Input/Output Reference pages on BigLadder Software.

  • src/model_editor/IddObjectDocUrl.hpp (new): header-only hash map (QHash<QString, QString>) mapping 300+ OS:* IDD type names to their BigLadder EnergyPlus 25.1 I/O Reference URLs
  • src/model_editor/InspectorGadget.cpp: renders the locked IDD type header in the right-sidebar inspector as a Qt::RichText hyperlink when a URL mapping exists
  • src/openstudio_lib/CollapsibleInspector.hpp/.cpp: extends CollapsibleInspector / CollapsibleInspectorHeader with an optional URL parameter; when set, the section title renders as a clickable link
  • src/openstudio_lib/SimSettingsView.cpp: wires 15 CollapsibleInspector section headers and the 3 top-level H1 labels (Run Period, Sizing Parameters, Timestep) to their BigLadder doc anchors

Coverage

Inspector gadget links cover most major OS object categories: zones, HVAC, coils, heat pumps, plant equipment, airflow, schedules, constructions/materials, controls, and more. Remaining categories (AirflowNetwork, Generators, EMS, etc.) are tracked for follow-up.

Test plan

  • Open a model in OpenStudioApp and click a component in the HVAC or Loads tab — confirm the type header in the right-sidebar inspector renders as a blue hyperlink and opens the correct BigLadder page in the default browser
  • Navigate to the Simulation Settings tab — confirm Run Period, Sizing Parameters, and Timestep H1 labels are clickable links, and all CollapsibleInspector section headers (Simulation Control, Shadow Calculation, etc.) show blue links
  • Confirm that object types with no URL mapping still display plain text (no broken link rendering)
  • Future: run scripts/check_doc_urls.py (to be added) to verify no stale anchor IDs — see notes below

Notes on stale-link checking

Two options were considered for a future automated check:

Option A (recommended): Python scriptscripts/check_doc_urls.py parses IddObjectDocUrl.hpp and SimSettingsView.cpp with regex to extract every URL, fetches each BigLadder page once (deduplicating by page), parses the HTML to check that the anchor ID actually exists, and reports broken mappings with source location. No build step, runs standalone, can be a CI check or pre-commit hook.

Option B: GTest — A DocUrl_GTest.cpp using QNetworkAccessManager that iterates the hash map and checks each URL. Fits the existing test infrastructure but network tests are slow and flaky in CI, and GTest does not provide a natural way to fetch-and-parse HTML for anchor verification.

Option A is preferred because the BigLadder server returns HTTP 200 for any anchor on an existing page — a plain HTTP HEAD check will silently miss renamed anchors. Verifying anchor IDs requires fetching the page HTML and scanning for id="..." attributes. Python's requests + html.parser handles that cleanly in ~80 lines.

Closes #160

🤖 Generated with Claude Code

…headers

Add IddObjectDocUrl.hpp mapping 300+ OS IDD type names to EnergyPlus 25.1
Input/Output Reference URLs. InspectorGadget::layoutText() now renders IDD
type headers as clickable hyperlinks in the right-sidebar inspector. Extend
CollapsibleInspector to accept an optional URL parameter, and wire 15 section
headers in SimSettingsView (plus the Run Period, Sizing Parameters, and
Timestep H1 labels) to their respective BigLadder doc anchors.

Closes openstudiocoalition#160

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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.

Add contextual help for fields in OS App

1 participant