Add tool to preview docs changes in a PR by samsrabin · Pull Request #3972 · ESCOMP/CTSM

samsrabin · 2026-04-26T21:20:25Z

Description of changes

Given a GitHub PR URL, download the code as if it had been merged and then build the docs.

Example on Casper:

module load podman
tools/contrib/preview_docs_pr.py https://github.com/ESCOMP/CTSM/pull/3972

Will clone to '/glade/derecho/scratch/samrabin/preview_docs_pr.ESCOMP.CTSM.pr-3972'
Downloading zip from GitHub...
Unzipping...
Code downloaded to: '/glade/derecho/scratch/samrabin/preview_docs_pr.ESCOMP.CTSM.pr-3972/ESCOMP-CTSM-6579501'
Getting submodules...
Building docs...
Cleaning documentation build directory...
Done.
Building documentation...
The HTML pages are in _build/html.
Done.

The updated files are in /glade/derecho/scratch/samrabin/preview_docs_pr.ESCOMP.CTSM.pr-3972/ESCOMP-CTSM-6579501/doc/_build/html
Doc source files directly touched (not deleted) by PR:
    tech_note/CN_Pools/CLM50_Tech_Note_CN_Pools.html
    _images/screenshot_5718.png
    tech_note/index.html
Note that changes to these or other files may indirectly affect other doc files! For example, if one of these files is a new/changed image, or a new/changed text file that's `include`d somewhere, or a text file with an updated label that's cross-referenced elsewhere. Or if a file outside doc/source/ that's `include`d in a doc file got changed.

Specific notes

Contributors other than yourself, if any: None

CTSM Issues Fixed (include github issue #): None

Are answers expected to change (and if so in what way)? No

Any User Interface Changes (namelist or namelist defaults changes)? No

Does this create a need to change or add documentation? Did you do so? No. It's currently in tools/contrib/ and thus unsupported.

Testing performed, if any: Testing on #3958 and this PR.

Revert the docs changes that were made on this PR for testing purposes.

…n, if available

samsrabin · 2026-04-27T17:52:18Z

Thanks @slevis-lmwg!

Done with 428defb Prevent "Using 'master' as the name for the initial branch" message

wwieder · 2026-04-27T18:54:31Z

My test failed. I did the following:

cd /glade/u/home/wwieder/ctsm-doc-preview
module load ncarenv/24.12
module load podman
tools/contrib/preview_docs_pr.py https://github.com/ESCOMP/CTSM/pull/3971

message:

Will clone to '/glade/derecho/scratch/wwieder/preview_docs_pr.ESCOMP.CTSM.pr-3971'
  Mergeability not yet computed, waiting 10 seconds and retrying(1/5)...
  Mergeability not yet computed, waiting 10 seconds and retrying(2/5)...
Downloading zip from GitHub...
Unzipping...
Code downloaded to: '/glade/derecho/scratch/wwieder/preview_docs_pr.ESCOMP.CTSM.pr-3971/ESCOMP-CTSM-fbd45ee'
Getting submodules...
Building docs...
Cleaning documentation build directory...
Documentation build failed.
Re-run with --verbose for full output.

Then running with --verbose:

tools/contrib/preview_docs_pr.py --verbose https://github.com/ESCOMP/CTSM/pull/3971

also failed

usage: preview_docs_pr.py [-h] [--dir EXTRACTION_DIR] [-o] pr_url
preview_docs_pr.py: error: unrecognized arguments: --verbose

wwieder · 2026-04-27T18:58:17Z

Should I be doing this on casper?

samsrabin · 2026-04-27T19:20:27Z

@wwieder I think this is related to whatever problem you had where you needed to load ctsm_pylib before building the docs. Could you reproduce that problem and tell me exactly what command you used and what all the printout was?

samsrabin · 2026-04-27T19:41:47Z

Should I be doing this on casper?

@wwieder Also yes, I would have thought this should work fine on Derecho, but I'm getting errors. So yeah please try on Casper.

wwieder · 2026-04-27T20:00:25Z

This worked on casper! Below is what I'm seeing for PR 3971, which provides updates for Sturm.

tools/contrib/preview_docs_pr.py https://github.com/ESCOMP/CTSM/pull/3971 -o
Will clone to '/glade/derecho/scratch/wwieder/preview_docs_pr.ESCOMP.CTSM.pr-3971'
Downloading zip from GitHub...
Deleting existing clone dir: '/glade/derecho/scratch/wwieder/preview_docs_pr.ESCOMP.CTSM.pr-3971/ESCOMP-CTSM-fbd45ee'
Unzipping...
Code downloaded to: '/glade/derecho/scratch/wwieder/preview_docs_pr.ESCOMP.CTSM.pr-3971/ESCOMP-CTSM-fbd45ee'
Getting submodules...
Building docs...
Cleaning documentation build directory...
Done.
Building documentation...
The HTML pages are in _build/html.
Done.

The updated files are in /glade/derecho/scratch/wwieder/preview_docs_pr.ESCOMP.CTSM.pr-3971/ESCOMP-CTSM-fbd45ee/doc/_build/html
Doc source files directly touched (not deleted) by PR:
    tech_note/Glacier/CLM50_Tech_Note_Glacier.html
    tech_note/Lake/CLM50_Tech_Note_Lake.html
    tech_note/References/CLM50_Tech_Note_References.html
    tech_note/Soil_Snow_Temperatures/CLM50_Tech_Note_Soil_Snow_Temperatures.html
Note that changes to these or other files may indirectly affect other doc files! For example, if one of these files is a new/changed image, or a new/changed text file that's `include`d somewhere, or a text file with an updated label that's cross-referenced elsewhere. Or if a file outside doc/source/ that's `include`d in a doc file got changed.

wwieder · 2026-04-27T20:00:59Z

@wwieder I think this is related to whatever problem you had where you needed to load ctsm_pylib before building the docs. Could you reproduce that problem and tell me exactly what command you used and what all the printout was?

I haven't been able to reproduce this error since last week.

samsrabin · 2026-04-27T20:06:51Z

Great, thanks Will! I'll go ahead and merge this. Then could you revert the changes you made to the docs docs in #3942?

ekluzek

This is great. It made it much easier to preview the documentation for a PR. I also added a softlink to the default directory for this on Scratch in VNC, which means I can pop this up really quickly.

I have a couple suggestions.

Change the script name to leave off the .py extention
Add a successfully done statement to the end
Use the ctsm_logging add_logging_args/process_logging_args to maange the --verbose argument

This reverts commit 56ccdae.

This reverts commit 9606321.

samsrabin · 2026-04-27T20:41:02Z

Done with 3dda069 Fix issue rendering figures that was surfaced by Revision of Chapter 2.16 Urban Model (CLMU) in technical note for CLM6 #3913

This reverts commit 41fedb9.

This reverts commit a977d84.

wwieder

Sorry, forgot to mark as approved

samsrabin self-assigned this Apr 26, 2026

samsrabin added the b4b bit-for-bit label Apr 26, 2026

samsrabin added 20 commits April 27, 2026 09:11

Initial work on preview_docs_pr.sh.

e49126f

preview_docs_pr.sh: Now does a basic clone and build.

123ac02

preview_docs_pr.sh: Now loads podman if on casper.

683f4fb

preview_docs_pr.sh: Name remote after owner during clone.

ef80432

preview_docs_pr.sh: Prepend clone dir with preview_docs_pr

65da828

preview_docs_pr.sh: Clone to subdir of /glade/derecho/scratch/samrabi…

7856bad

…n, if available

preview_docs_pr.sh: Clone may not be within an existing git repo

20bcf0c

preview_docs_pr.sh: Add a set -u.

af9427d

Add preview_docs_pr.py.

9affd1a

Test adding a new docs image.

9606321

Test removing a doc file.

56ccdae

preview_docs_pr.py: Empty commit to avoid git lfs problems.

0b32557

preview_docs_pr.py: Delete test printout.

367075c

preview_docs_pr.py: Delete unused load_podman.

fa3eaf7

preview_docs_pr.py: Handle empty result.stdout.

bdf3c7b

preview_docs_pr.py: Factor out print_files_msg().

9e62c9c

preview_docs_pr.py: Fix subprocess call.

96a11a1

preview_docs_pr.py: print_files_msg(): Fix dict vs str

d5608fb

preview_docs_pr.py: Fix print_files_msg().

8125f37

preview_docs_pr.py: Fix "The update files are in" msg.

5d3126e

samsrabin force-pushed the docs-pr-preview-tool branch from 4a8365f to 5d3126e Compare April 27, 2026 15:12

samsrabin added the enhancement new capability or improved behavior of existing capability label Apr 27, 2026

samsrabin marked this pull request as ready for review April 27, 2026 15:27

samsrabin changed the title ~~[WIP] Add tool to preview docs changes in a PR~~ Add tool to preview docs changes in a PR Apr 27, 2026

samsrabin changed the base branch from master to b4b-dev April 27, 2026 15:30

samsrabin added 3 commits April 27, 2026 09:32

preview_docs_pr.py: Wait 10 secs for mergeability re-check.

4849a4a

preview_docs_pr.py: Suppress git messages.

27cc36a

preview_docs_pr.py: Resolve pylint complaints.

05de758

preview_docs_pr.py: Specify branch name on git init.

428defb

samsrabin added 2 commits April 27, 2026 13:34

preview_docs_pr.py: Pass -v/--verbose to build_docs.

b224d99

preview_docs_pr.py: Fix --dir help msg.

eac4a50

ekluzek approved these changes Apr 27, 2026

View reviewed changes

Comment thread tools/contrib/preview_docs_pr

Comment thread tools/contrib/preview_docs_pr

Comment thread tools/contrib/preview_docs_pr

samsrabin added 3 commits April 27, 2026 14:14

Rename to preview_docs_pr.

9323437

Revert "Test removing a doc file."

9cf0959

This reverts commit 56ccdae.

Revert "Test adding a new docs image."

39639e2

This reverts commit 9606321.

samsrabin mentioned this pull request Apr 27, 2026

Revision of Chapter 2.16 Urban Model (CLMU) in technical note for CLM6 #3913

Merged

6 tasks

samsrabin and others added 5 commits April 27, 2026 15:42

preview_docs_pr: --verbose now shows stdout for git cmds.

803ae76

preview_docs_pr: Fix docs build (git lfs).

3dda069

preview_docs_pr: Factor out new function set_up_git().

f78385e

Test removing a doc file.

41fedb9

Test adding a new docs image.

a977d84

samsrabin force-pushed the docs-pr-preview-tool branch from d799948 to a977d84 Compare April 27, 2026 21:42

samsrabin and others added 5 commits April 27, 2026 15:50

preview_docs_pr: Fix print_files_msg check under --verbose.

de022d9

preview_docs_pr: Do complete git-fleximod.

3159b85

Revert "Test removing a doc file."

09f3130

This reverts commit 41fedb9.

Revert "Test adding a new docs image."

5bf4b7b

This reverts commit a977d84.

preview_docs_pr: Simplify git remote add (HTTPS always works).

7fdc988

wwieder approved these changes Apr 27, 2026

View reviewed changes

samsrabin merged commit ff80be8 into ESCOMP:b4b-dev Apr 27, 2026
4 checks passed

Conversation

samsrabin commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of changes

Specific notes

Uh oh!

samsrabin commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wwieder commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wwieder commented Apr 27, 2026

Uh oh!

samsrabin commented Apr 27, 2026

Uh oh!

samsrabin commented Apr 27, 2026

Uh oh!

wwieder commented Apr 27, 2026

Uh oh!

wwieder commented Apr 27, 2026

Uh oh!

samsrabin commented Apr 27, 2026

Uh oh!

ekluzek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samsrabin commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wwieder left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

samsrabin commented Apr 26, 2026 •

edited

Loading

samsrabin commented Apr 27, 2026 •

edited

Loading

wwieder commented Apr 27, 2026 •

edited

Loading

samsrabin commented Apr 27, 2026 •

edited

Loading