fre make documentation updates part 1

[laurenchilutti]

Describe your changes

Updated fremake.py:

• added a top level module doc string that references the README, click docs, and readthedocs pages when necessary to avoid dupication.
• elaborated on the help messages for the click options and renamed "internal use" variables to begin with a leading underscore consistent with PEP8
• Split out the -njobs/-j command option to be -gj/--gitjobs and -mj/makejobs to differentiate the two usages of jobs in all, create_compile, and create_checkout. This required modification to run_fremake_script.py, test_run_fremake_builds.py, and test_run_fremake.py
• Created a custom class that inherits from click.Group so that the fre make subtools are listed in the order they are defined rather than alphabetical order. I think this will visually show a fre user the expected order one would call these commands.
• Explicitly named the click commands for better code readability - without explicitly naming, a reader of the code needs to have background knowledge that in click: "The name of the command defaults to the name of the function, converted to lowercase, with underscores _ replaced by dashes -"
• Also gave the fre make all command a short help description, as the full description gets cutoff at an awkward point when you do fre make --help. The full help description will be displayed with fre make all --help

Updated docs:

• Added a glossary with common terms
• so far only has target and platform (i plan to expand upon this_
• the terms will be sorted in alphabetical order when Sphinx generates the readthedocs.
• Added te glossary to the index.rst

Issue ticket number and link (if applicable)

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.10%. Comparing base (b34af59) to head (a43ae12).
⚠️ Report is 81 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #735      +/-   ##
==========================================
+ Coverage   82.76%   84.10%   +1.33%     
==========================================
  Files          68       70       +2     
  Lines        4525     4780     +255     
==========================================
+ Hits         3745     4020     +275     
+ Misses        780      760      -20     

Flag	Coverage Δ
unittests	84.10% <100.00%> (+1.33%)	⬆️

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

Files with missing lines	Coverage Δ
fre/make/fremake.py	95.58% <100.00%> (+0.27%)	⬆️
fre/make/run_fremake_script.py	97.14% <100.00%> (+0.08%)	⬆️

... and 14 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

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

🚀 New features to boost your workflow:

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

[laurenchilutti]

This is ready for a review. I plan to make more updates in future PRs, but want to keep the changes small enough in each PR so that they are easy to review.

[mlee03]

Round 1 of reviews, what do you think of the made suggestions?

[laurenchilutti]

Should be ready to merge - glossary can always be improved as we go.

[mlee03]

Tiny changes, other than that, what's here is a good start for the chatbot~

[mlee03]

Let's discuss at 11

[laurenchilutti]

ready for another review!

[mlee03]

one more change. officially seeing it, it looks like a run-on.

The term refers to the fre make argument which specifies compiler options for model compilation. The value of the string must start with prod, repro, or debug followed by optional, supplementary tags that are separated by -. for example, a target can have value of repro-openmp, prod-openmp-lto. See [link] for more details @singhd789 these targets are defined somwhere in fre-cli right?

[singhd789]

Hm, I think they only place they are maybe discussed is here:

fre-cli/fre/pp/README.md

Lines 144 to 149 in ad432b1

	The *target* is the option that was used for the model compiler. There are currently 4-ish options we expect to see:
	prod - Used for production experiments. Runs
	repro - Used when reproducing past results for regression tests. Slower than debug, faster than production.
	debug - Used when debugging. Fastest runtime.
	openmp - Used when compiled and linked with OpenMP. Can be put onto the end of another target (e.g. prod-openmp)
	hdf5 - Added directives to generate HDF5-based netCDF files. Can be put onto the end of another target (e.g. repro-hdf5)

and honestly...it could be better and moved elsewhere (like in fre make docs - especially because they're not really used much in fre pp)

[mlee03]

how about linking this class? https://github.com/NOAA-GFDL/fre-cli/blob/main/fre/make/gfdlfremake/targetfre.py

[singhd789]

I'm curious if there can be any other targets passed that we don't define in the code. At the moment, I think if a user were to pass other supplementary targets besides openmp and lto, it would still create the necessary fre make scripts (even it if was a nonexistent target which is not the best).

If we don't want this to happen (and just stick to/control the targets/supplementary targets), maybe we list the potential combinations in click.Choice (like this: https://github.com/NOAA-GFDL/fre-cli/blob/main/fre/yamltools/freyamltools.py#L19) and say "for target choices, see fre make all --help". This might be adding too much though, maybe we can do that in the next iteration!

[singhd789]

For now, I personally like giving the target / supplementary target names here