Update Users Guide

[j-derrico]

Description
Fixes Issue #177, Updating the UW Tools users guide
Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes need updates to the documentation. I have made corresponding changes to the documentation
• My changes generate no new warnings
• New and existing tests pass with my changes
• Any dependent changes have been merged and published

[christinaholtNOAA]

@j-derrico This looks great! Thank you!

I built the docs locally and looked around in the browser. I didn't see any failures, and I can't seem to see why the github check failed. Do you have any ideas.

If we can't spot that with fresh eyes later, maybe we just merge it and see if perhaps it is a permissions issue or something similar?

The content looks good.

[WeirAE]

Odd, it does build ok for me too, and technically it does say 'build successful' before it fails. I'll have to recheck with fresh eyes. There are several warnings on small formatting things but I'd be surprised if that was it. The first part reads a little ChatGPT-y, but its good!

[j-derrico]

Is it possible to log in to readthedocs and see what happens when it builds from that side?

[christinaholtNOAA]

@j-derrico Nice suggestion, I'm seeing that it also passed in the build history on RtDs as well. I'd say we go ahead with the merge, if you're okay with that this morning? I can push it through.

[christinaholtNOAA]

I think the failure is likely related to this chunk of code in jobs/build_documentation.sh.

warning_file=${DOCS_DIR}/_build/warnings.log
if [ -s $warning_file ]; then
  cp -r ${DOCS_DIR}/_build/warnings.log artifact/doc_warnings.log
  cp artifact/doc_warnings.log artifact/documentation
  exit 1
fi

It seems like we aren't tolerating anything in the warnings file.

EDIT: I see that my warnings file on my local build is not empty (workflow-tools/docs/_build/warnings.log)

[WeirAE]

Ah, so it was the warnings - it looked like mostly indent and label complaints, I think thats fixable

[jprestop]

@christinaholtNOAA and @j-derrico I was out of the office when you were originally discussing the warnings in this PR. I just wanted to follow up in case you didn't already know that in the GitHub Actions tab, you can find the Documentation run for the PR that failed and you can see there is an artifact at the bottom of that page called documentation_warnings.log that you can download and look at to see what the warnings are. I hope that is helpful information (which you can just ignore if you already knew). :)