Update docs related to NOAA CSPs

[weihuang-jedi]

Description

With CSPs now capable or compile and run global-workflow for ATM forecast only, coupled, and gefs, and many changes at ParallelWorks, Docs should be updated to reflect all these changes.

Resolves #3042

Type of change

• Bug fix (fixes something broken)
• New feature (adds functionality)
• Maintenance (code refactor, clean-up, new CI test, etc.)
• [x ] Docs updating

Change characteristics

• Is this a breaking change (a change in existing functionality)? NO
• Does this change require a documentation update? YES
• Does this change require an update to any of the following submodules? NO (If YES, please add a link to any PRs that are pending.)
  • EMC verif-global
  • GDAS
  • GFS-utils
  • GSI
  • GSI-monitor
  • GSI-utils
  • UFS-utils
  • UFS-weather-model
  • wxflow

How has this been tested?

• checked the appearance on web site.

Checklist

• Any dependent changes have been merged and published
• [x ] My code follows the style guidelines of this project
• [x ] I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have documented my code, including function, input, and output descriptions
• [x ] My changes generate no new warnings
• New and existing tests pass with my changes
• This change is covered by an existing CI test or a new one has been added
• Any new scripts have been added to the .github/CODEOWNERS file with owners
• [x ] I have made corresponding changes to the system documentation if necessary

[KateFriedman-NOAA]

Approve pending resolution of comment from other reviewer and approval by other reviewer.

[KateFriedman-NOAA]

@weihuang-jedi What is this empty file (docs/source/references.bib) that was just added?

[weihuang-jedi]

Let me check with Gillian, to see what is that for.

[gspetro-NOAA]

@KateFriedman-NOAA, a file containing citation information is required when using the sphinxcontrib.bibtex extension. It can be named anything, but the global-workflow conf.py file already calls it references.bib. Ideally, it is intended to contain citation information, like in the SRW App's references.bib file (referenced in the SRW UG Introduction and linked in other parts of the docs). When I generated the global-workflow docs locally, it came up with a warning about sphinxcontrib.bibtex being misconfigured. The options seemed to be either (1) add the file it is expecting (references.bib, in this case) or (2) remove the extension, the bibtex_bibfiles = ['references.bib'] line, and the references.bib file. It depends how likely you think you are to want to cite some scientific papers in the docs. We do that for SRW and Land DA. I just chose the option that seemed least invasive.

Technically, the docs bring up another warning when built locally: WARNING: unsupported theme option 'footer_icons' given. I would have removed the footer line from conf.py, but I wasn't sure if there was a reason you all wanted/needed it in there. Since it's a preexisting issue not related to Wei's work, and I didn't know offhand how to fix it to maintain/implement the desired functionality, I didn't address it.
That said, I'd encourage testing the docs! It's very easy to add an integration with GitHub where docs are built for each PR (you literally check off one box in readthedocs.org to enable it). Then you can add the -W option to the doc Makefile, which will cause doc builds to fail on warning or error. This ensures you'll see any issues with the docs right away, rather than assuming that developers are building the docs as part of testing. I also recommend setting the version of sphinx in the requirements file. There's more to say on that, but in general, sometimes docs build well locally because the developer is using a different version of sphinx (or other packages) than the repository.

[gspetro-NOAA]

@weihuang-jedi Has made all requested changes, and the docs build without any new errors on my system.

[KateFriedman-NOAA]

Good to know, thanks @gspetro-NOAA !