Doc improvements for 2026.01 by ceblanton · Pull Request #925 · NOAA-GFDL/fre-cli

ceblanton · 2026-06-30T21:06:26Z

Describe your changes

Replace scratchpad developer notes in postprocess.rst with complete prose and YAML examples for timeseries, climatologies, statics, surface masking, refineDiag, preAnalysis, and legacy cshell analysis
Remove reference to abandoned analysis-scripts repo in intro
Add preAnalysis scripts section (new, distinct from refineDiag)
Rename "Legacy refineDiag scripts" → "refineDiag scripts"
Rename "Analysis scripts" → "Legacy cshell analysis scripts"
Remove NEEDS UPDATING TODO from tools/pp.rst; add pointer to usage guide
Replace stale 2025 placeholder in Run FMS model with 2026.03 release note and link to legacy frerun documentation

Issue ticket number and link (if applicable)

Fixes #XXX (replace XXX with the issue number and GitHub will autolink the PR to the issue)

Checklist before requesting a review

I ran my code
I tried to make my code readable
I tried to comment my code
I wrote a new test, if applicable
I wrote new instructions/documentation, if applicable
I ran pytest and inspected it's output
I ran pylint and attempted to implement some of it's feedback
No print statements; all user-facing info uses logging module

Note: If you are a code maintainer updating the tag or releasing a new fre-cli version, please use the release_procedure.md template. To quickly use this template, open a new pull request, choose your branch, and add ?template=release_procedure.md to the end of the url.

- Replace scratchpad developer notes in postprocess.rst with complete prose and YAML examples for timeseries, climatologies, statics, surface masking, refineDiag, preAnalysis, and legacy cshell analysis - Remove reference to abandoned analysis-scripts repo in intro - Add preAnalysis scripts section (new, distinct from refineDiag) - Rename "Legacy refineDiag scripts" → "refineDiag scripts" - Rename "Analysis scripts" → "Legacy cshell analysis scripts" - Remove NEEDS UPDATING TODO from tools/pp.rst; add pointer to usage guide - Replace stale 2025 placeholder in Run FMS model with 2026.03 release note and link to legacy frerun documentation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

codecov · 2026-06-30T21:25:03Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.09%. Comparing base (ad94447) to head (c539da1).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #925   +/-   ##
=======================================
  Coverage   82.09%   82.09%           
=======================================
  Files          67       67           
  Lines        3736     3736           
=======================================
  Hits         3067     3067           
  Misses        669      669

Flag	Coverage Δ
unittests	`82.09% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ad94447...c539da1. Read the comment docs.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Reorder nav (FRE tools before Usage), fold container into Setup, rename sections to match old structure (Yaml files, Build a model, Running an experiment, Postprocessing, User plugins), add About/Schema/ Variables/Directories subsections to Yaml files, expand postprocess with online/offline PP, sub-year, pressure levels, gap-filling, and validation sections, extract user plugin docs to user_plugins.rst. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Lead Setup with module load instructions for NOAA-GFDL systems (GFDL one-liner, Gaea with module use first), followed by conda install for generic systems. Remove README pointer and local-clone section from Setup; expand For developers Local/Editable Installation with the actual clone + conda env + pip install steps. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

New top-level pages linking to public fre-examples repo and internal GFDL MSD configurations, plus a stub AI assistance page for the forthcoming chatbot offering. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

laurenchilutti · 2026-07-01T14:17:05Z

+.. _ai-assistance:
+
+=============
+AI assistance


I would recommend keeping this out of the documentation until an AI Assistant is ready.

laurenchilutti · 2026-07-01T14:21:05Z

@@ -0,0 +1,15 @@
+=====================


Check the build logs of your read the docs build.

I see one warning that can easily be resolved
/home/docs/checkouts/readthedocs.org/user_builds/noaa-gfdl-fre-cli/checkouts/925/docs/examples.rst:1: WARNING: Title overline too short.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

singhd789 · 2026-07-01T14:15:56Z

+
+.. code-block:: console
+
+ fre yamltools validate-yaml -y am5.yaml -e experiment_name -p platform -t target


This tool unfortunately doesn't exist (yet!). At the moment, the validation is baked into some other tools (fre pp configure-yaml and fre make tools)

Whoops, yeah. I'll update to fre yamltools combine-yamls.. that's okay, yes?

I think it's being validated in the fre pp configure-yaml step.

singhd789 · 2026-07-07T19:10:51Z

+
+ conda config --append channels noaa-gfdl
+ conda config --append channels conda-forge
+ conda create --name fre-<version> --channel noaa-gfdl --channel conda-forge fre-cli::<version>


Shouldn't this be fre-cli==<version> at the end? Ryan tried this out and conda was reading fre-cli as a channel and not a package

Right you are! (do AI hallucination emojis exist yet?)

ilaflott

we're still changing the preAnalysis language to something different, yeah?

ilaflott · 2026-07-23T16:07:55Z

+Output file names must differ from any existing history file names. Multiple refineDiag scripts
+can be defined, each under its own label.
+
+preAnalysis scripts


no more preAnalysis? first step user script, or what have you?

ceblanton and others added 3 commits June 30, 2026 18:46

Add Configuration examples and AI assistance sections

4ef3c8e

New top-level pages linking to public fre-examples repo and internal GFDL MSD configurations, plus a stub AI assistance page for the forthcoming chatbot offering. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ceblanton requested review from ilaflott and laurenchilutti July 1, 2026 14:10

singhd789 requested review from mlee03 and singhd789 July 1, 2026 14:14

laurenchilutti requested changes Jul 1, 2026

View reviewed changes

Remove AI assistance page (not yet ready)

be7bd5d

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

singhd789 reviewed Jul 2, 2026

View reviewed changes

singhd789 reviewed Jul 7, 2026

View reviewed changes

Merge branch 'main' into docs-202601

c539da1

ilaflott reviewed Jul 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Doc improvements for 2026.01 - #925

Doc improvements for 2026.01#925
ceblanton wants to merge 6 commits into
mainfrom
docs-202601

ceblanton commented Jun 30, 2026

Uh oh!

codecov Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

laurenchilutti Jul 1, 2026

Uh oh!

laurenchilutti Jul 1, 2026

Uh oh!

singhd789 Jul 1, 2026 •

edited

Loading

Uh oh!

ceblanton Jul 2, 2026

Uh oh!

singhd789 Jul 2, 2026

Uh oh!

singhd789 Jul 7, 2026

Uh oh!

ceblanton Jul 7, 2026 •

edited

Loading

Uh oh!

ilaflott left a comment

Uh oh!

ilaflott Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		.. code-block:: console

		fre yamltools validate-yaml -y am5.yaml -e experiment_name -p platform -t target

Uh oh!

Conversation

ceblanton commented Jun 30, 2026

Describe your changes

Issue ticket number and link (if applicable)

Checklist before requesting a review

Uh oh!

codecov Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

laurenchilutti Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

laurenchilutti Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

singhd789 Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ceblanton Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

singhd789 Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

singhd789 Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

ceblanton Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ilaflott left a comment

Choose a reason for hiding this comment

Uh oh!

ilaflott Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov Bot commented Jun 30, 2026 •

edited

Loading

singhd789 Jul 1, 2026 •

edited

Loading

ceblanton Jul 7, 2026 •

edited

Loading