feat: add clickable EnergyPlus doc links throughout OpenStudioApp UI

[Ski90Moo]

Summary

Implements the enhancement requested in #160 — adds clickable hyperlinks from UI section headers and IDD type headers to the relevant EnergyPlus 25.1 Input/Output Reference pages on BigLadder Software. Tooltips show the full URL before clicking.

Inspector / IDD object headers

• 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

Left-sidebar category headers

• src/openstudio_lib/OSCollapsibleItemHeader.hpp/.cpp: extends OSCollapsibleItemHeader with an optional URL; when set, the category name renders as a clickable blue link
• src/openstudio_lib/ModelObjectTypeListView.hpp/.cpp: adds a new constructor accepting vector<tuple<IddObjectType, string, QString>> to thread URLs through to each header
• Loads tab: People, Lights, Electric/Gas/Steam/Other Equipment, Internal Mass, Water Use Equipment, Hot Water Equipment definitions
• Constructions subtab: Constructions, Air Boundary, Internal Source, C-factor Underground Wall, F-factor Ground Floor
• Materials subtab: all 14 material types (standard, no-mass, air gap, all window material variants)
• Other Schedules subtab: Schedule Constant, Schedule Compact, Schedule File

Section headers (SimSettings pattern)

• src/openstudio_lib/CollapsibleInspector.hpp/.cpp: extends CollapsibleInspectorHeader with an optional URL; section title renders as a clickable link
• src/openstudio_lib/SimSettingsView.cpp: 15 CollapsibleInspector section headers and 3 H1 labels (Run Period, Sizing Parameters, Timestep)
• src/openstudio_lib/LocationTabView.cpp: Weather File and Design Days headers
• src/openstudio_lib/YearSettingsWidget.cpp: Daylight Savings Time header
• src/openstudio_lib/GroundTemperatureView.hpp/.cpp: all 5 Ground Temperatures sidebar entries
• src/openstudio_lib/LifeCycleCostsTabView.cpp: Life Cycle Cost Parameters and NIST Fuel Escalation Rates headers
• src/openstudio_lib/BuildingInspectorView.cpp: North Axis label (Facility tab)

Build infrastructure

• cmake/FindOpenStudioSDK.cmake: defines BIGLADDERSOFTWARE_DOC_BASE_URL as a single versioned CMake variable (EnergyPlus 25.1)
• src/model_editor/CMakeLists.txt and src/openstudio_lib/CMakeLists.txt: pass the URL as a compile definition so all files share a single source of truth for the base URL

Test plan

• Open a model — confirm IDD type headers in the right-sidebar inspector render as blue hyperlinks and open the correct BigLadder page
• Navigate to Simulation Settings — confirm all CollapsibleInspector section headers and H1 labels are clickable links
• Check Loads, Constructions, Materials, and Other Schedules sidebar categories render as blue links
• Check Site tab (Weather File & Design Days, Ground Temperatures, Life Cycle Costs) section headers are linked
• Check Facility tab North Axis label is linked
• Hover over any link to confirm the tooltip shows the full URL before clicking
• Confirm object types with no URL mapping still display plain text (no broken link rendering)

Closes #160

🤖 Generated with Claude Code

[macumber]

Looks pretty good, the one thing I would ask for is a tooltip which shows you the url before you click

[Ski90Moo]

Thanks for the feedback! Tooltips showing the full URL have been added to all clickable doc links — both in the inspector header (via layoutHeaderText) and in the CollapsibleInspectorHeader. Additionally, this branch has been extended to add doc links to several other parts of the UI: the left-sidebar category headers on the Loads, Constructions, Materials, and Other Schedules tabs, as well as section headers on the Site tab (Weather File, Design Days, Daylight Savings Time, Ground Temperatures), Life Cycle Costs tab, and the Facility tab (North Axis).

[Ski90Moo]

Addressed the BIGLADDERSOFTWARE_DOC_BASE_URL feedback: removed the target_compile_definitions approach and added a bigladdersoftwareDocBaseUrl() accessor to OpenStudioApplicationPathHelpers following the existing .cxx.in pattern. The URL is configured from BIGLADDERSOFTWARE_DOC_BASE_URL in FindOpenStudioSDK.cmake, so it will be visible alongside the EnergyPlus version bump each release. All call sites updated to use QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl()).

[macumber]

Suggested change

	QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl()) + "group-simulation-parameters.html#building";
	QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl()) + iddObjectDocUrl("OS:Building");

It would be better to handle all of these using iddObjectDocUrl so all the url fragments are in one place.

[Ski90Moo]

Addressed in 2b58110 — the inline URL fragments were consolidated into iddObjectDocUrl(), so the call site now just uses iddObjectDocUrl(QStringLiteral("OS:Building")) directly.

[macumber]

@Ski90Moo one thing I found is that you have to use the same version of clang-format that the CI is using, 18.1.3, other versions of clang-format don't find the same issues as CI.

[Ski90Moo]

Thanks for the heads-up. The clang-format on this machine was the pip-installed 18.1.8 package shadowing the system LLVM install. Switched to 18.1.3 to match CI — both versions produce identical output on the PR-touched files, so the formatting commit pushed in 8a7f8d1 should satisfy the check once the workflows are approved to run.

[Ski90Moo]

Addressed the remaining review comments:

layoutHeaderText cleanup — Adopted your refactored version: removed the index parameter, simplified the structure.

BuildingInspectorView.cpp — Switched to iddObjectDocUrl(QStringLiteral("OS:Building")) so the URL fragment lives in one place alongside all the others. Swapped the OpenStudioApplicationPathHelpers include for IddObjectDocUrl.hpp.

Warning log — Added qWarning() << "Cannot find doc url for: " + iddTypeName; before the empty return in iddObjectDocUrl.

Group URL lookup — Added iddGroupDocUrl(groupName) to IddObjectDocUrl.hpp mapping OpenStudio.idd \group names (e.g. "OpenStudio Simulation", "OpenStudio Materials") to their BigLadder page URLs. Groups that span multiple EnergyPlus chapters (e.g. "OpenStudio HVAC") are intentionally omitted. All 395 URL references pass check_doc_urls.py.

[macumber]

Suggested change

	T{IddObjectType::OS_Construction, "Constructions", sce + "#construction-000"},
	T{IddObjectType::OS_Construction, "Constructions", iddObjectDocUrl(QStringLiteral("OS:Construction"),

These urls are already defined in IddObjectDocUrl.hpp, we should use those definitions rather than duplicate them here. Same thing for all the other urls in this file and others such as:

• https://github.com/openstudiocoalition/OpenStudioApplication/pull/876/changes#diff-041047d3606ed5e7fec54dcfe4e8e7ce2f5720433717aaa1e00936250e7140b6R105
• https://github.com/openstudiocoalition/OpenStudioApplication/pull/876/changes#diff-e35d718a8caea938a126dcce1d7f7baae6e2878d2325aa60c129adc74f6254e0R159
• https://github.com/openstudiocoalition/OpenStudioApplication/pull/876/changes#diff-25e93e6585f3692c885d623d1223853ca5b3362b49d23fb99e8bbeb6d1ba357dR53
• etc

[Ski90Moo]

Thank you macumber, agreed. Done in 42c02c2 — added 18 missing type→URL entries to IddObjectDocUrl.hpp (Construction variants, WindowMaterial variants, Schedule:File, GroundTemperature:Shallow/Deep, RunPeriodControl:DaylightSavingTime, ConvergenceLimits, ZoneCapacitanceMultiplier:ResearchSpecial, Output types, LifeCycleCost types) and replaced all bigladdersoftwareDocBaseUrl() + hardcoded fragment patterns across 9 view files (ConstructionsView, MaterialsView, LoadsView, ScheduleOthersView, SimSettingsView, GroundTemperatureView, LifeCycleCostsTabView, LocationTabView, YearSettingsWidget) with iddObjectDocUrl() / iddGroupDocUrl() calls.

[macumber]

@jmarrec do you have thoughts on this PR? Both this PR and the BCL one rely on an external webpage which we don't have control over. I have thought that it might be better to make the URLs configurable in preferences rather than hard coded. However, if the URLs ever change it is also likely that the API/site layout would change which would break the integration. I am leaning towards something like 1) Make the URLs configurable, 2) Test the URLs at startup and disable functionality if they are not available. What do you both think? That could be implemented on a separate PR if we want to do it. I think this PR is setup for it well, if we return an empty URL when the integration test fails the tooltips just won't be added.

[jmarrec]

I like the idea of adding some help!

But I think I'm quite against linking to the Big Ladder website because like you said we have zero control over it. The URL may change, the links could be broken in a new version, etc. The BCL endpoint changing recently is a pain that makes it quite clear this is something we should avoid.

I've already build the E+ HTML documentation recently, it's quite simple to do with pandoc really. I'm not quite sure if we are allowed to host that on a domain we control or not though (license wise), but this is something we should perhaps investigate.

[macumber]

Maybe we just build the html and then ship with the app?

[Ski90Moo]

Thanks for digging into this, @macumber and @jmarrec — these are fair concerns and I want to share the motivation behind the feature so the tradeoff is clearer.

The original driver was actually the in-progress i18n work (#873): once the GUI is translated, a non-English-speaking user is still stuck with English-only EnergyPlus/OpenStudio documentation. Rather than have OpenStudio take on the burden of translating that documentation ourselves, the idea is to get the user to the relevant doc page quickly so they can use their own browser's built-in translator (Chrome, Edge, etc. all do this well now) — no extra maintenance burden on us, and the user gets a translation tuned to their specific language and reading level.

On the "we don't control BigLadder" concern — that's true, but I'd note a few things that make this a different kind of dependency than the BCL endpoint:

• These links point to archived, version-specific EnergyPlus documentation pages (e.g., a specific E+ version's input/output reference). They aren't a live API tied to current data — once a version's docs are published, they don't get rewritten or recategorized.
• BigLadder has hosted these archived docs at stable URLs for years without restructuring them, even as new EnergyPlus versions ship (the new version's docs just get a new path; old paths keep working).
• The PR is already structured so a missing/changed mapping degrades gracefully — iddObjectDocUrl()/iddGroupDocUrl() return an empty string when there's no entry, so no tooltip/link is shown rather than a broken one.

I think @macumber's suggestion (configurable base URL + an availability check at startup that disables the feature gracefully) is a great safety net regardless of which docs we ultimately link to, and could be layered on without much rework — happy to tackle that as a fast-follow on this PR or a separate one.

@jmarrec's idea of bundling locally-built E+ HTML docs is appealing for full independence, but it's a much larger scope change (build pipeline, packaging size, licensing question you raised, and keeping it in sync with the bundled E+ version). If that's the direction the project wants to go long-term, I'm happy to help, but I'd suggest it's worth treating as its own initiative rather than blocking this PR — which, as currently designed, fails safe if the links ever do break.

Let me know how you'd like to proceed — happy to adjust scope based on your call.

[jmarrec]

I am going to do some legwork to inquire whether we can host it somewhere (we've discussed with the E+ dev team to have it on energyplus.net or readthedocs in the past, and otherwise I'll see if we can do it on a domain we control here) . I'll keep you posted.

[Ski90Moo]

I am going to do some legwork to inquire whether we can host it somewhere (we've discussed with the E+ dev team to have it on energyplus.net or readthedocs in the past, and otherwise I'll see if we can do it on a domain we control here) . I'll keep you posted.

That would be great! Thank you @jmarrec.

[macumber]

@Ski90Moo let's include this in the RC2

In order to avoid depending on more online sources (which have caused us problems), let's update this to work with installed docs in the package. To do this, I think the basic steps are:

• Add a FindEnergyPlus CMake that downloads and finds EnergyPlus
  • Try to make it where all we have to do is update the EnergyPlus version
  • https://github.com/NatLabRockies/OpenStudio/blob/develop/CMakeLists.txt#L668
  • https://github.com/NatLabRockies/OpenStudio/blob/develop/CMake/FindEnergyPlus.cmake
• Build the EnergyPlus Input Output documentation to html
  • https://github.com/NatLabRockies/EnergyPlus/tree/develop/doc/input-output-reference
  • https://github.com/NatLabRockies/EnergyPlus/blob/develop/.github/workflows/build_documentation.yml
  • https://github.com/NatLabRockies/EnergyPlus/blob/develop/CMakeLists.txt
  • https://github.com/NatLabRockies/EnergyPlus/blob/develop/doc/readthedocs/README.md
• Add install code to install the html docs in our package under EnergyPlus/doc
• Update your code to point to local base URL derived from the paths in OpenStudioApplicationPathHelpers.hpp

@jmarrec might be able to give you a little more specifics

[Ski90Moo]

@jmarrec — thanks again for the ep_doc_html export, it's been really useful. We've gone ahead and wired it in as a stopgap per @macumber's suggestion: the app now downloads your export, from the link you provided, at configure time (MD5-verified), installs it alongside the app, and all of IddObjectDocUrl.hpp's doc links now point at the local copy instead of bigladdersoftware.com. (commit on our fork's feat/doc-links-inspector)

Confirmed working: real cross-page hyperlinks, native MathML equations (no JS/bitmaps), and all 393 of our existing anchor references resolve correctly against your export's HTML.

A few questions as we look at making this permanent rather than a one-off download:

1. Can we run the build pipeline behind this ourselves, in CI or at release time, rather than depending on a manual export each time?
2. Is the pipeline tied to a specific EnergyPlus tag/version the way the official releases are, so we could pin our build to whatever version the OpenStudio SDK bundles?
3. The output currently pulls Bootstrap/Bootstrap-Icons/Highlight.js from jsdelivr/cdnjs CDNs — we'd want to vendor those locally so the docs work fully offline (same reason we're moving off bigladdersoftware.com). Any objection to that, or a reason it's CDN-hosted today that we should know about?
4. Found one broken internal link in the export: 1.3-input-output-descriptions-document.html (and 4 other pages) link to 1.4-sec:api-usage.html (colon), but the actual file is 1.4-sec_api-usage.html (underscore) — looks like a label-sanitization mismatch between the cross-reference generator and the output-filename generator in the Pandoc pipeline. Confirmed it's the only broken local link out of 8,519 internal cross-references in the export.

[jmarrec]

• Can we run the build pipeline behind this ourselves, in CI or at release time, rather than depending on a manual export each time?
• Is the pipeline tied to a specific EnergyPlus tag/version the way the official releases are, so we could pin our build to whatever version the OpenStudio SDK bundles?

Yes, you do want to build documentation for a specific E+ tag.
Don't worry about doing that yourself, I need to figure out how I upstream that. And there are 2 releases of EnergyPlus per year, so it's fine to do manually if needed (I don't have to, I wired it up into github actions already)

• The output currently pulls Bootstrap/Bootstrap-Icons/Highlight.js from jsdelivr/cdnjs CDNs — we'd want to vendor those locally so the docs work fully offline (same reason we're moving off bigladdersoftware.com). Any objection to that, or a reason it's CDN-hosted today that we should know about?

The HTML docs were meant to be online, so CDN made sense. I also happen to have a single-page version where it was nice to have everything in one file (images can be base64 encoded)

Anyways, that's easy to change, download a few files, do a global sed.

• Found one broken internal link in the export: 1.3-input-output-descriptions-document.html (and 4 other pages) link to 1.4-sec:api-usage.html (colon), but the actual file is 1.4-sec_api-usage.html (underscore) — looks like a label-sanitization mismatch between the cross-reference generator and the output-filename generator in the Pandoc pipeline. Confirmed it's the only broken local link out of 8,519 internal cross-references in the export.

Yeah I actually need to figure that out, I hit this error when uploading to github artifact too (the colon was rejected for upload as it's not NTFS compliant)