Document preview_namelist usage

[rljacob]

The logic for when preview_namelist is called and how it keeps namelists in sync should be documented. Its a script available to user's so we should tell them when they might need to run it if they don't want CIME to do it all for them.

[rljacob]

For a regular create_newcase, I think this is the sequence and reasons:

• Called during case.build before the actual build:
  • because some builds need namelist info. First time all namelists are built.
• Called in case.submit
  • because users may have changed an xml file after building.
• Called in case.run
  • because users may have changed an xml file while the job is in the queue before it runs.

[jedwards4b]

You mean preview_namelists

[rljacob]

Thanks. Fixed it.

[rljacob]

According to @jgfouca in #1203 (comment), this is the sequence for create_test:

1. Called post-SETUP by create_test (if compare or generate baselines)
2. Called in build.py for sharedlib build
3. Called in case.submit
4. Called once per invocation of case_run.run_model

[github-actions]

This issue is stale because it has been open 90 days with no activity. Remove stale label or comment or this will be closed in 5 days.

[github-actions]

This issue is stale because it has been open 90 days with no activity. Remove stale label or comment or this will be closed in 5 days.

[rljacob]

still need this.