Skip to content

Help to Sphinx #2145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
cpaulgilman wants to merge 27 commits into
base: develop
Choose a base branch
from
Open

Help to Sphinx #2145

cpaulgilman wants to merge 27 commits into from

Conversation

@cpaulgilman
Copy link
Collaborator

@cpaulgilman cpaulgilman commented Feb 5, 2026

Description

This is a major reworking of SAM's Help system to migrate from proprietary Help & Manual to open source Sphinx documentation.

For high-level build instructions for Windows, see https://github.com/NatLabRockies/SAM/wiki/Windows-Build-Instructions#9-build-help-optional (also on Mac and Linux build instructions).

For detailed build instructions and information, see https://github.com/NatLabRockies/SAM/blob/help-to-sphinx/README.md.

Fixes #2110

Corresponding branches and PRs:

Build from Develop branches of SSC, WEX, LK and SAM-private.

Unit Test Impact:

None.

Checklist

  • requires help revision and I added that label
  • adds, removes, modifies, or deletes variables in existing compute modules
  • adds a new compute module
  • changes defaults
  • [ X ] I've tagged this PR to a milestone

@cpaulgilman
Initial implementation
154d747 
* Use native web browser to display Help
* Use `wxHtmlWindow` to display version information regardless of platform
@cpaulgilman
Merge branch 'develop' into help-about
60b2cb7
@cpaulgilman
Move HelpWin to main.cpp
4107c86
@cpaulgilman
Updates for macOS tests
7e06141
@cpaulgilman
Restore SAM icon to help window
39f84aa
@cpaulgilman
Clean up code for removed Help window buttons
15f3466
@cpaulgilman
Remove unused webview references
1fac79c
@cpaulgilman
Help source files
78709fe 
* Move old files from `doc` folder to `SAM-documentation` repo. These are developer notes on old issues before we had the SAM Documentation repo.
* Add new .rst source files for Sphinx-generated Help to `doc` folder.
* Delete old HTML help files generated by Help & Manual from `runtime` folder.
@cpaulgilman
Delete commented code
cb0f169
@cpaulgilman
Remove commented code
6e9e2b1
@cpaulgilman
Merge branch 'help-about' into help-to-sphinx
d8609f6
@cpaulgilman
New Help IDs for Sphinx-generated help
f480c42 
Help ID is path to HTML file with no extension <folder>/<filename>. For example Help ID "battery-storage/battery_dispatch_fom" points to battery_dispatch_fom.html in "/help/html/battery-storage" folder.
@cpaulgilman
Fix source files to be consistent with updated Help IDs
2c08028
@cpaulgilman
Add documentation for help generation instructions and revision log
60c69cf
@cpaulgilman
Update Help instructions and configuration
3f39ef4
@cpaulgilman
Restore F1 key for Help in event table
c53d4a1
@cpaulgilman
Help IDs for new PV UI input pages
74fa79d
@cpaulgilman
Update build instructions
4ac85df
@cpaulgilman
Initial Help revisions for PV UI redesign
de77fe0
@cpaulgilman
Fix broken URLs in Help
ffca0f1
@cpaulgilman
Help revisions for PV UI redesign
a28af18
@cpaulgilman
Merge branch 'develop' into help-to-sphinx
9a46534
@cpaulgilman
Help updates
7e40a14
@cpaulgilman
Fix list alignment in Help
10ee021
@cpaulgilman
Merge branch 'develop' into help-to-sphinx
c9a4e35
@cpaulgilman
Add note about Help on Mac
4ed9188
@cpaulgilman cpaulgilman added this to the SAM 2026 Release milestone Feb 5, 2026
@cpaulgilman cpaulgilman self-assigned this Feb 5, 2026
@brtietz
Copy link
Collaborator

brtietz commented Feb 9, 2026 •
edited
Loading

Edit: I was able to debug the issue I posted previously. The path sent to window.cpp is:
file:///C:\Users\bmirletz\source\repos\sam_dev\SAM\deploy\runtime\help\html\pvwatts/pvwatts_location_and_resource.html

The actual path is: "C:\Users\bmirletz\source\repos\sam_dev\SAM\deploy\runtime\help\pvwatts\pvwatts_location_and_resource.html"

I was able to re-run xcopy to get it to work with xcopy .\build\html ..\deploy\runtime\help\html /s Should the Windows build instructions be updated?

@brtietz
Copy link
Collaborator

brtietz commented Feb 9, 2026

Appears to be a path error with incentives and depreciation: 15:26:08: Error: Failed to open URL "file:///C:\Users\bmirletz\source\repos\sam_dev\SAM\deploy\runtime\help\html\incentives/incentives.html" in default browser. (error 2: The system cannot find the file specified.)

Actual folder name is incentives-and-depreciation

@cpaulgilman
Copy link
Collaborator Author

cpaulgilman commented Feb 11, 2026

I was able to re-run xcopy to get it to work with xcopy .\build\html ..\deploy\runtime\help\html /s Should the Windows build instructions be updated?

Yes. That should be fixed now.

@cpaulgilman
Copy link
Collaborator Author

cpaulgilman commented Feb 11, 2026

Actual folder name is incentives-and-depreciation

Should be fixed with 15e9f28.

brtietz
brtietz approved these changes Feb 11, 2026
View reviewed changes
Copy link
Collaborator

@brtietz brtietz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the fixes!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@brtietz brtietz brtietz approved these changes

@sjanzou sjanzou Awaiting requested review from sjanzou

@janinefreeman janinefreeman Awaiting requested review from janinefreeman

@tyneises tyneises Awaiting requested review from tyneises

@qualand qualand Awaiting requested review from qualand

@mjprilliman mjprilliman Awaiting requested review from mjprilliman

@taylorbrown75 taylorbrown75 Awaiting requested review from taylorbrown75

Assignees

@cpaulgilman cpaulgilman

Labels

None yet

Projects

None yet

Milestone

SAM 2026 Release

Development

Successfully merging this pull request may close these issues.

Dead links in help to fix for 2025 fall release

2 participants

@cpaulgilman @brtietz