[develop] Update documentation for Rocoto XML changes

[christinaholtNOAA]

DESCRIPTION OF CHANGES:

Updates the User's Guide sections on configuring the workflow, and added a section on Defining a Workflow.

I have not updated the FAQ or Tutorial pages. People using older versions may still need that information, so I'll leave it to other folks to handle that transition.

Type of change

• 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

TESTS CONDUCTED:

• hera.intel
• orion.intel
• cheyenne.intel
• cheyenne.gnu
• gaea.intel
• jet.intel
• wcoss2.intel
• NOAA Cloud (indicate which platform)
• Jenkins
• fundamental test suite
• comprehensive tests (specify which if a subset was used)

DEPENDENCIES:

DOCUMENTATION:

This is only documentation.

ISSUE:

n/a

CHECKLIST

• My code follows the style guidelines in the Contributor's Guide
• I have performed a self-review of my own code using the Code Reviewer's Guide
• 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 do not require updates to the documentation (explain).
• My changes generate no new warnings
• New and existing tests pass with my changes
• Any dependent changes have been merged and published

LABELS (optional):

A Code Manager needs to add the following labels to this PR:

• Work In Progress
• bug
• enhancement
• documentation
• release
• high priority
• run_ci
• run_we2e_fundamental_tests
• run_we2e_comprehensive_tests
• Needs Cheyenne test
• Needs Jet test
• Needs Hera test
• Needs Orion test
• help wanted

CONTRIBUTORS (optional):

@gspetro-NOAA

[MichaelLueken]

@christinaholtNOAA Thank you very much for updating the documentation! I have noted a minor issue in ConfigWorkflow.rst that should assist in readability and an issue in RunSRW.rst where it looks like you meant to add a link to the DefineWorkflow chapter, but this link wasn't provided.

[MichaelLueken]

@christinaholtNOAA Thank you very much for applying the changes! Everything looks good.

[gspetro-NOAA]

@christinaholtNOAA When I build the docs, I get this warning:
/Users/gillianpetro/holtSRW/docs/UsersGuide/source/Tutorial.rst:168: WARNING: undefined label: workflow-switches
I think you'll just need to fix the crosslink on line 158 of Tutorial.rst to link to an appropriate section (based on the updated ConfigWorkflow.rst) or remove the reference if it doesn't make sense anymore.

[christinaholtNOAA]

@gspetro-NOAA I wasn't sure what to do there. I noticed the warning and left it because I do not feel comfortable updating the tutorial. My initial thought was that the warning kind of serves as a "to do" for that update.

I can take the cross-reference out to fix the warning, but the text will still be quite wrong.

[gspetro-NOAA]

@christinaholtNOAA It might make sense to add DefineWorkflow after the RocotoInfo section.

[gspetro-NOAA]

@christinaholtNOAA I think that at a minimum, you should remove the line "For a detailed description of the workflow-switches: variables, see Section %s" because once that is committed to develop, the crosslink won't render properly in the docs (it will literally say "Section %s" instead of having a crosslink, which I think would be more confusing to users). You could also delete the workflow-switches section entirely and copy-paste your instructions from the RunSRW chapter on how to turn on plotting, but if that seems like a can of worms, don't worry about it. I can update the rest of that chapter when we do the next release.

[natalie-perlin]

Somehow, workflow_switches are no longer used in the current SRW version. I missed the moment they were taken out, and it's very unfortunate for a general user. What is the way for the user specify whether to run a particular task?..

[gspetro-NOAA]

@natalie-perlin Christina's edits to RunSRW.rst in this PR cover that. She wrote in this PR description that she will not update the full tutorial chapter at this time. I just need her to remove the one line in the Tutorial chapter that creates a broken link in order to approve. The rest will be updated later ahead of the release.

[gspetro-NOAA]

Thanks for the update! Code builds without error. :)