Skip to content

Commit 60c69cf

Browse files
cpaulgilmancpaulgilman
committed
Add documentation for help generation instructions and revision log
1 parent 2c08028 commit 60c69cf

File tree

2 files changed

+127
-3
lines changed

2 files changed

+127
-3
lines changed

‎doc/readme.md‎

Lines changed: 106 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
# SAM Help Build Instructions
1+
# SAM Help
22

3-
These instructions are for building SAM's Help system in HTML from text files in reStructuredText (.rst) format with the Sphinx documentation generator.
3+
These instructions are for writing and editing content and building SAM's Help system.
44

5-
Sphinx is a Python package that converts .rst files into structured html documents. It can also be used to generate a PDF document using LaTex.
5+
Writing and editing content requires knowledge of reStructuredText (.rst) format. ReStructuredText is a text markup language, see https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html.
6+
7+
The build process uses the Sphinx documentation generator. Sphinx is a Python package that converts .rst files into structured html documents and documents in other formats, see https://www.sphinx-doc.org/en/master/.
68

79
## Requirements
810

@@ -12,8 +14,109 @@ Sphinx is a Python package that converts .rst files into structured html documen
1214

1315
Tested on Windows with Python 3.12.10 and GNU Make 4.4.1.
1416

17+
## Build Instructions
18+
19+
1. Set up a Python virtual environment and install the packages listed in requirements.txt.
20+
21+
You only need to build the environment once. After the environment is built, you can start with Step 2 to bulid Help.
22+
23+
2. Open a terminal window and go to the SAM doc folder.
24+
25+
```
26+
cd path/to/sam_dev/SAM/doc
27+
```
28+
29+
3. Activate the Python environment.
30+
31+
For example, using Python's virtual environment manager `venv`:
32+
33+
```
34+
path/to/sam-help-venv/Scripts/activate
35+
```
36+
37+
3. Run Make.
38+
39+
```
40+
make html
41+
```
42+
43+
To clean the build first, run `make clean`.
44+
45+
4. If there are any build errors, fix them by editing the appropriate .rst file(s).
46+
47+
5. When the build finishes, HTML and associated files should be in the `path/to/sam_dev/SAM/deploy/runtime/help/html` folder.
48+
49+
To see Help, open the index.html file.
50+
1551
## Help Context IDs
1652

53+
Help context IDs are defined in different places depending on the context.
54+
55+
The Help context ID consists of the folder and file name of the HTML for the Help topic.
56+
57+
For example, the Help topic for the behind-the-meter Battery Dispatch input page is "battery-storage/battery_dispatch_btm".
58+
59+
The Help ID is the path to the HTML file without the `.html` extension. The extension is added by the `ShowHelp()` function in `SAM/main.cpp`.
60+
61+
## SAM Input Pages
62+
63+
Help IDs for SAM input pages are defined in `startup.lk`. The `addpage()` function for the input page "help" parameter points to the folder and file name of the HMTL file for the page's Help topic.
64+
65+
For example, for the **Battery Dispatch** page for behind the meter batteries, the help id is defined by the `'help' = 'battery-storage/battery_dispatch_btm'` parameter:
66+
67+
```
68+
addpage( [[ {'name'='Battery Dispatch Peak Shaving BTM', 'caption'='Peak Shaving'} ],
69+
[ {'name'='Battery Dispatch Grid Power Targets', 'caption'='Grid Power Targets'} ],
70+
[ {'name'='Battery Dispatch Battery Power Targets', 'caption'='Battery Power Targets'}],
71+
[ {'name'='Battery Dispatch Manual', 'caption'='Manual'}],
72+
[ {'name'='Battery Dispatch Retail Rate', 'caption'='Retail Rate'} ]],
73+
{ 'sidebar'='Battery Dispatch',
74+
'help'='battery-storage/battery_dispatch_btm',
75+
'exclusive_var' = 'batt_dispatch_excl',
76+
'exclusive_header_pages' = ['Battery Dispatch Common', 'Battery Dispatch Standalone Options BTM'],
77+
'exclusive_tabs'=true, 'exclusive_hide'=true, 'bin_name'='Battery' } );
78+
```
79+
80+
81+
## SAM Windows
82+
83+
Help IDs for SAM windows are defined by the event handler in the window definition.
84+
85+
For example, for the "Combine Cases" window (`SAM/combinecases.cpp`):
86+
87+
```
88+
void CombineCasesDialog::OnEvt(wxCommandEvent& e)
89+
{
90+
switch (e.GetId())
91+
{
92+
case wxID_HELP:
93+
SamApp::ShowHelp("window-reference/win_combine_cases");
94+
break;
95+
case ID_chlCases:
96+
{
97+
...
98+
}
99+
```
100+
101+
For the "Edit Losses" window (`SAM/lossadj.cpp`):
102+
103+
```
104+
void OnCommand( wxCommandEvent &e )
105+
{
106+
switch( e.GetId() )
107+
{
108+
case wxID_HELP:
109+
SamApp::ShowHelp("window-reference/win_edit_losses");
110+
break;
111+
```
112+
113+
HTML files generated by Sphinx are organized into folders of related topics.
114+
115+
To find all SAM window Help IDs, search the SAM project for "wxID_HELP", or more specifically "case wxID_HELP" and "if (evt.GetId() == wxID_HELP)".
116+
117+
## Editing .rst Files
118+
119+
recommend text editor that can open folder as workspace to open `SAM/doc` folder.
17120

18121
## Notes
19122

‎doc/sam-help-revision-log.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# SAM Help Revision Log
2+
3+
## To Do
4+
5+
Copy content from "Custom HTF" to new `window-reference/win_edit_material_properties` and revise. Topic is broke in SAM 2025.4.16.
6+
7+
New Help topic for Advanced NOHRSC Download window, see https://github.com/NREL/SAM/pull/2089.
8+
9+
IPH MSLF revisions: https://github.com/NREL/SAM/pull/1960
10+
11+
Wind SSC inputs/outputs: https://github.com/NREL/ssc/pull/1186
12+
13+
Note registration email is sent to NSRDB for weather file downloads. Also update registration post on forum.
14+
15+
MSPT SolarPILOT differences between UI / SSC, and between Mac/Linux and Windows. See "MSPT / SolarPILOT cross-platform results" email.
16+
17+
Update excess generation option descriptions pending update to dgrules field in URDB. See Brian email "Sample dg options and checkboxes" 10/13/2025, saved in Revisions 2026 folder.
18+
19+
DSCR debt sizing note, see Brian email 10/31/2025 "Addtional thoughts on debt sizing error message".
20+
21+
## Complete

0 commit comments

Comments
 (0)