diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 2cd48a33e..92b2020fc 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,9 +9,19 @@ build: tools: python: "3.9" +# Set the version of Python and other tools you might need +build: + os: ubuntu-20.04 + tools: + python: "3.9" + # You can also specify other tool versions: + # nodejs: "16" + # rust: "1.55" + # golang: "1.17" + # Build documentation in the docs/ directory with Sphinx sphinx: - configuration: docs/UsersGuide/source/conf.py + configuration: doc/UsersGuide/source/conf.py # Build documentation with MkDocs #mkdocs: @@ -23,4 +33,4 @@ formats: all # Optionally set the version of Python and requirements required to build your docs python: install: - - requirements: docs/UsersGuide/requirements.txt \ No newline at end of file + - requirements: doc/UsersGuide/requirements.txt \ No newline at end of file diff --git a/docs/CODE_STYLE.md b/doc/CODE_STYLE.md similarity index 100% rename from docs/CODE_STYLE.md rename to doc/CODE_STYLE.md diff --git a/docs/Release_Notes.hafs.v1.0.0.md b/doc/Release_Notes.hafs.v1.0.0.md similarity index 100% rename from docs/Release_Notes.hafs.v1.0.0.md rename to doc/Release_Notes.hafs.v1.0.0.md diff --git a/docs/UsersGuide/Makefile b/doc/UsersGuide/Makefile similarity index 66% rename from docs/UsersGuide/Makefile rename to doc/UsersGuide/Makefile index d0c3cbf10..7749fd8b3 100644 --- a/docs/UsersGuide/Makefile +++ b/doc/UsersGuide/Makefile @@ -3,18 +3,27 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build +SPHINXOPTS = -a -n +SPHINXBUILD = sphinx-build SOURCEDIR = source BUILDDIR = build +LINKCHECKDIR = $(BUILDDIR)/linkcheck + +.PHONY: help Makefile linkcheck # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +doc: + make clean + $(MAKE) linkcheck + $(MAKE) html + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(SPHINXOPTS) $(SOURCEDIR) $(LINKCHECKDIR) # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -w $(BUILDDIR)/warnings.log diff --git a/docs/UsersGuide/README.md b/doc/UsersGuide/README.md similarity index 100% rename from docs/UsersGuide/README.md rename to doc/UsersGuide/README.md diff --git a/docs/UsersGuide/make.bat b/doc/UsersGuide/make.bat similarity index 95% rename from docs/UsersGuide/make.bat rename to doc/UsersGuide/make.bat index 6247f7e23..9534b0181 100644 --- a/docs/UsersGuide/make.bat +++ b/doc/UsersGuide/make.bat @@ -1,35 +1,35 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/UsersGuide/requirements.in b/doc/UsersGuide/requirements.in new file mode 100644 index 000000000..26c778f4a --- /dev/null +++ b/doc/UsersGuide/requirements.in @@ -0,0 +1,3 @@ +sphinx>=6.0.0 +sphinx_rtd_theme +sphinxcontrib-bibtex diff --git a/doc/UsersGuide/requirements.txt b/doc/UsersGuide/requirements.txt new file mode 100644 index 000000000..11faea2f3 --- /dev/null +++ b/doc/UsersGuide/requirements.txt @@ -0,0 +1,78 @@ +# +# This file is autogenerated by pip-compile with Python 3.11 +# by the following command: +# +# pip-compile requirements.in +# +alabaster==0.7.16 + # via sphinx +babel==2.14.0 + # via sphinx +certifi==2024.2.2 + # via requests +charset-normalizer==3.3.2 + # via requests +colorama==0.4.6 + # via sphinx +docutils==0.20.1 + # via + # pybtex-docutils + # sphinx + # sphinx-rtd-theme + # sphinxcontrib-bibtex +idna==3.6 + # via requests +imagesize==1.4.1 + # via sphinx +jinja2==3.1.3 + # via sphinx +latexcodec==2.0.1 + # via pybtex +markupsafe==2.1.5 + # via jinja2 +packaging==23.2 + # via sphinx +pybtex==0.24.0 + # via + # pybtex-docutils + # sphinxcontrib-bibtex +pybtex-docutils==1.0.3 + # via sphinxcontrib-bibtex +pygments==2.17.2 + # via sphinx +pyyaml==6.0.1 + # via pybtex +requests==2.31.0 + # via sphinx +six==1.16.0 + # via + # latexcodec + # pybtex +snowballstemmer==2.2.0 + # via sphinx +sphinx==7.2.6 + # via + # -r requirements.in + # sphinx-rtd-theme + # sphinxcontrib-bibtex + # sphinxcontrib-jquery +sphinx-rtd-theme==2.0.0 + # via -r requirements.in +sphinxcontrib-applehelp==1.0.8 + # via sphinx +sphinxcontrib-bibtex==2.6.2 + # via -r requirements.in +sphinxcontrib-devhelp==1.0.6 + # via sphinx +sphinxcontrib-htmlhelp==2.0.5 + # via sphinx +sphinxcontrib-jquery==4.1 + # via sphinx-rtd-theme +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==1.0.7 + # via sphinx +sphinxcontrib-serializinghtml==1.1.10 + # via sphinx +urllib3==2.2.1 + # via requests diff --git a/docs/UsersGuide/source/Introduction.rst b/doc/UsersGuide/source/Backgroundinfo/Introduction.rst similarity index 92% rename from docs/UsersGuide/source/Introduction.rst rename to doc/UsersGuide/source/Backgroundinfo/Introduction.rst index 91c2bd6c9..36160dcfe 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/doc/UsersGuide/source/Backgroundinfo/Introduction.rst @@ -6,6 +6,6 @@ Introduction The Hurricane Analysis and Forecast System (HAFS) is the Unified Forecast System (UFS) Hurricane Application. HAFS is the :term:`FV3`-based multi-scale model and data assimilation system capable of providing tropical cyclone (TC) analyses and forecasts of the inner core structure of TCs (including hurricanes and typhoons). HAFS capabilities are key to improving size and intensity predictions, as well as predictions of the large-scale environment that is known to influence a TC’s motion. HAFS development targets an operational analysis and forecast system for hurricane forecasters with reliable, robust and skillful guidance on TC track and intensity (including rapid intensification), storm size, genesis, storm surge, rainfall, and tornadoes associated with TCs. It will provide an advanced analysis and forecast system for cutting-edge research on modeling, physics, data assimilation, and coupling to earth system components for high-resolution TC predictions within the outlined Next Generation Global Prediction System (NGGPS)/Strategic Implementation Plan (SIP) objectives of the Unified Forecast System (UFS). Currently, HAFS is under active development with collaborative efforts among NCEP/EMC, AOML, GFDL, GSL, ESRL/NESII, OFCM/AOC, DTC, NCAR, and the broader research community. -For information about how to contribute to HAFS development, please review the `code repository governance `__. +For information about how to contribute to HAFS development, please review the :hafs-wiki:`code repository governance `. The HAFS repository is located at ``__. diff --git a/docs/UsersGuide/source/TechnicalOverview.rst b/doc/UsersGuide/source/Backgroundinfo/TechnicalOverview.rst similarity index 100% rename from docs/UsersGuide/source/TechnicalOverview.rst rename to doc/UsersGuide/source/Backgroundinfo/TechnicalOverview.rst diff --git a/doc/UsersGuide/source/Backgroundinfo/index.rst b/doc/UsersGuide/source/Backgroundinfo/index.rst new file mode 100644 index 000000000..a90fcd497 --- /dev/null +++ b/doc/UsersGuide/source/Backgroundinfo/index.rst @@ -0,0 +1,9 @@ +Background Information +======================================================== + +.. toctree:: + :maxdepth: 3 + + Introduction + TechnicalOverview + diff --git a/docs/UsersGuide/source/ExtQuickStart.rst b/doc/UsersGuide/source/BuildingRunningTesting/ExtQuickStart.rst similarity index 100% rename from docs/UsersGuide/source/ExtQuickStart.rst rename to doc/UsersGuide/source/BuildingRunningTesting/ExtQuickStart.rst diff --git a/docs/UsersGuide/source/QuickStart.rst b/doc/UsersGuide/source/BuildingRunningTesting/QuickStart.rst similarity index 100% rename from docs/UsersGuide/source/QuickStart.rst rename to doc/UsersGuide/source/BuildingRunningTesting/QuickStart.rst diff --git a/docs/UsersGuide/source/RegressionTest.rst b/doc/UsersGuide/source/BuildingRunningTesting/RegressionTest.rst similarity index 100% rename from docs/UsersGuide/source/RegressionTest.rst rename to doc/UsersGuide/source/BuildingRunningTesting/RegressionTest.rst diff --git a/doc/UsersGuide/source/BuildingRunningTesting/index.rst b/doc/UsersGuide/source/BuildingRunningTesting/index.rst new file mode 100644 index 000000000..0d7a45b60 --- /dev/null +++ b/doc/UsersGuide/source/BuildingRunningTesting/index.rst @@ -0,0 +1,9 @@ +Building, Running, and Testing HAFS +======================================================== + +.. toctree:: + :maxdepth: 3 + + QuickStart + ExtQuickStart + RegressionTest \ No newline at end of file diff --git a/docs/UsersGuide/source/GitHubBasicSteps.rst b/doc/UsersGuide/source/ContributorsGuide/GitHubBasicSteps.rst similarity index 94% rename from docs/UsersGuide/source/GitHubBasicSteps.rst rename to doc/UsersGuide/source/ContributorsGuide/GitHubBasicSteps.rst index 2a493571e..dd6f6c92f 100644 --- a/docs/UsersGuide/source/GitHubBasicSteps.rst +++ b/doc/UsersGuide/source/ContributorsGuide/GitHubBasicSteps.rst @@ -37,7 +37,7 @@ Users need a GitHub account to work with the HAFS repository. Instructions for c Users should replace ``USERNAME`` with their GitHub username in the command above. - .. hint:: See `GitHub forking projects `__ + .. hint:: See `GitHub forking projects `__ ==================================================== Create a Feature Branch from the ``develop`` Branch @@ -89,7 +89,7 @@ Submit a Pull Request for Inclusion into the Authoritative HAFS Repository To propose changes for inclusion into the authoritative HAFS repository, developers need to create a pull request. -#. Navigate to https://github.com/hafs-community/HAFS/pulls and click on *New pull request*. +#. Navigate to :hafs-repo:`pulls` and click on *New pull request*. #. Click on *Compare across forks*. a. Set the base repository to *hafs-community/HAFS* and the base branch to ``develop``. b. Set the head repository to *YOUR_GITHUB_USERNAME/HAFS* and the compare branch to ``feature/mybranch``. diff --git a/doc/UsersGuide/source/ContributorsGuide/HAFSCodeContributionGuidelines.rst b/doc/UsersGuide/source/ContributorsGuide/HAFSCodeContributionGuidelines.rst new file mode 100644 index 000000000..6d24091f7 --- /dev/null +++ b/doc/UsersGuide/source/ContributorsGuide/HAFSCodeContributionGuidelines.rst @@ -0,0 +1,214 @@ +.. _HAFSCodeContributionGuidelines: + +*********************************************** +UFS Repository Code Management Guidance (Draft) +*********************************************** + +The authoritative HAFS repository is located at https://github.com/hafs-community/HAFS. The HAFS repository maintains a main branch for development called ``develop``. The HEAD of ``develop`` reflects the latest peer-reviewed development changes and is read-only for users. It points to regularly updated hashes for individual subcomponents. The ``develop`` branch is protected; changes can only be made by pull request, not by pushing directly to the repository. + +.. _gitflow: + +GitFlow +======== + +Contributors who have write access to the `HAFS `_ project in GitHub should follow `GitFlow development guidelines `_ for any development performed directly in the ``hafs-community/HAFS`` repository. Changes to the ``develop`` branch require a pull request (see :ref:`Fork and PR Overview `). + +Contributors who do not have write permissions for the HAFS repository must conduct all development in a fork and submit changes via pull request (PR) to the authoritative repository. This process is summarized in the :ref:`Fork and PR Overview ` below. + +.. _fork-pr-overview: + +Fork and PR Overview +===================== + +.. note:: + + Thank you to the Unified Workflow (UW) team for allowing us to adapt their Fork and PR Model overview for use in HAFS. The original can be viewed in the `uwtools` :uw:`documentation `. + + +Contributions to the HAFS project are made via a :github-docs:`Fork` and :github-docs:`Pull Request (PR)` model. GitHub provides a thorough description of this contribution model in their `Contributing to a project` :github-docs:`Quickstart`, but the steps, with respect to HAFS contributions, can be summarized as: + +#. :github-docs:`Create an issue ` to document proposed changes. +#. :github-docs:`Fork` the HAFS repository into your personal GitHub account. +#. :github-docs:`Clone` your fork onto your development system. +#. :github-docs:`Create a branch` in your clone for your changes. All development should take place on a branch, *not* on ``develop``. +#. :github-docs:`Make, commit, and push changes` in your clone / to your fork. +#. When your work is complete, :github-docs:`create a pull request (PR)` to merge your changes. + +For future contributions, you may delete and then recreate your fork or configure the official ``HAFS`` repository as a :github-docs:`remote repository` on your clone and :github-docs:`sync upstream changes` to stay up-to-date with the official repository. + +General Coding Standards +========================= + +* The HAFS repository follows the :term:`NCEP` Central Operations (NCO) :nco:`WCOSS Implementation Standards <>`. +* The HAFS repository must not contain source code for compiled programs. Only scripts and configuration files should reside in this repository. +* All bash scripts must explicitly be ``#!/bin/bash`` scripts. They should not be login-enabled (i.e., scripts should not use the ``-l`` flag). +* All code must be indented appropriately and conform to the style of existing scripts (e.g., local variables should be lowercase, global variables should be uppercase). +* No personal software installations (including libraries or code) or personal directories may be incorporated into HAFS repository code. + +Development and Testing Process +================================= + +#. **Create issue:** Open an :hafs-repo:`issue ` in the HAFS repository to document proposed changes. See :ref:`Opening an Issue ` for detailed instructions. +#. **Fork & Clone HAFS:** :github-docs:`Fork` the :hafs-repo:`HAFS repository<>` into your personal GitHub account and :github-docs:`clone` your fork onto your development system if you have not already done so. +#. **Create a branch** in your clone for your changes. All development should take place on a branch, not on ``develop``. Branches are typically named as follows, where ``[name]`` is a one-word description of the branch: + + * ``bugfix/[name]``: Fixes a demonstrably incorrect portion of code + * ``feature/[name]``: Adds a new feature to the code or improves an existing portion of the code + * ``text/[name]``: Changes elements of the repository that do not impact the compiled code in any way (e.g., changes to README, documentation, comments, changing quoted Registry elements, white space alignment). + * Only code managers may create ``release/*`` or ``production/*`` branches, which are used for public or operational releases, respectively. `Information on versioning `_ is available on the *ufs-community* wiki. + + Users will need to sync the branches in their fork with the authoritative HAFS repository periodically. +#. **Development:** Perform and test changes in the feature branch (not on ``develop``!). Document changes to the workflow and capabilities in the RST files so that the HAFS documentation stays up-to-date. +#. **Testing:** Test code modifications on as many platforms as possible, and request help with further testing from the code management team when unable to test on all Level 1 platforms. The bare minimum testing required before opening a PR is to run the regression tests on at least one supported machine. :numref:`Section %s ` of the HAFS User's Guide provides instructions on HAFS regression testing. +#. **Pull Request:** When your work is complete, :github-docs:`create a pull request` to merge your changes. When a PR is initiated, the :ref:`PR template ` autofills. Developers should use the template to provide information about the PR in the proper fields. See the guidelines in the :ref:`Making a Pull Request ` section for more details on making a good pull request. +#. **Merge** - When review and testing are complete, a code manager will merge the PR into ``develop`` (or another specified branch). +#. **Cleanup** - After the PR is merged, the code developer should delete the branch on their fork and close the issue. Feature branches are intended to be short-lived, concentrated on code with one sole purpose, and applicable to a single PR. A new feature branch should be created when subsequent code development continues. + +.. note:: + + Communication with code managers and the repository code management team throughout the process is encouraged. + +.. _open-issue: + +Opening an Issue +================= + +All changes to HAFS should be associated with a :hafs-repo:`GitHub Issue `. Developers should search the existing issues in the HAFS repository before beginning their work. If an issue does not exist for the work they are doing, they should create one prior to opening a new pull request. If an issue does exist, developers should be sure to collaborate to avoid duplicative work. + +To open an issue, click on :hafs-repo:`"New Issue"` within the HAFS GitHub repository. + +Choose from three options: + +#. :hafs-repo:`Bug Report `: Report specific problems ("bugs") in the code using the following template: + + .. code-block:: console + + ## Description + Provide a clear and concise description of what the bug is. + Also give a description of what behavior you expected to happen. + + ### To Reproduce: + What machines are you seeing this with? + Give explicit steps to reproduce the behavior if possible. + 1. do this + 2. then that + 3. then, oops, look at the bug + + ## Additional context (optional) + Add any other context about the problem here. + Directly reference any issues or PRs in this or other repositories that this is related to, and describe how they are related. Examples: + - needs to be fixed also in ufs-community/ufs-weather-model/issues/ + - dependent upon noaa-emc/upp/pull/ + + ## Output (optional) + + **Screenshots** + If applicable, drag and drop screenshots to help explain your problem. + + **output logs** + If applicable, include relevant output logs. + Either drag and drop the entire log file here (if a long log) or + + ``` + paste the code here (if a short section of log) + ``` + +#. :hafs-repo:`Feature Request `: New features and feature enhancements fall under this category. Propose features and enhancements using the following template. Optional sections may be deleted. + + .. code-block:: console + + ## Description + Provide a clear and concise description of the requested feature/capability. + + ## Proposed solution + How should the new feature/capability be added? If you have thoughts on the implementation strategy, please share them here. + + ## Status (optional) + Do you (or a colleague) plan to work on adding this feature? + + ## Related to (optional) + Directly reference any related issues or PRs in this or other repositories, and describe how they are related. Examples: + - fixed by hafs-community/hafs/pull/ + - dependent upon ufs-community/ufs-weather-model/pull/ + - associated with noaa-emc/upp/pull/ + - related to hafs-community/GSI/issues/ + +#. :hafs-repo:`Other `: Open a blank issue, and use the "Feature Request" template above as a starting point to describe the issue. + +For all issue reports, indicate whether this is: + #. A problem that you plan to work on and submit a PR for + #. A problem that you will **not** work on but that requires attention + #. A suggested improvement + +After filling out the issue report, click on "Submit new issue." + +.. _make-pr: + +Making a Pull Request +====================== + +All changes to the HAFS ``develop`` branch should be handled via GitHub’s "Pull Request" (PR) functionality. When creating your PR, please follow these guidelines, specific to the HAFS project: + +* Ensure that your PR is targeting the base repository ``hafs-community/HAFS`` and an appropriate base branch (usually ``develop``). +* Before making a pull request, ensure that your branch is sync'd with the corresponding branch in the authoritative repository (usually ``develop``). All conflicts must be resolved, and regression tests should be passing on at least one supported platform. +* **Complete PR template.** Your PR will appear pre-populated with a :ref:`template ` that you should complete. Provide an informative synopsis of your contribution, crosslink the issue(s) and dependencies, and indicate what testing has been conducted. You may tidy up the description by removing boilerplate text and non-selected checklist items. +* **Create draft PR.** Use the pull-down arrow on the green button below the description to initially create a :github-docs:`draft pull request`. + + * Once your draft PR is open, visit its *Files changed* tab and add comments to any lines of code where you think reviewers will benefit from more explanation. Try to save time by proactively answering questions you suspect reviewers will ask. + +* **Open PR.** Once your draft PR is marked up with your comments and ready for review, return to the *Conversation* tab and click the *Ready for review* button. + + * A default set of reviewers will automatically be added to your PR. You may add or request others, if appropriate. Pull requests will be reviewed and approved by at least two code reviewers, at least one of whom must have write permissions on the repository. Reviewers may make comments, ask questions, or request changes on your PR. Respond to these as needed, making commits in your clone and pushing to your fork/branch. Your PR will automatically be updated when commits are pushed to its source branch in your fork, so reviewers will immediately see your updates. When a PR has met the contribution and testing requirements and has been approved by two code reviewers, a code manager will merge the PR. + +.. _pr-template: + +PR Template +------------ + +Here is the template that is provided when developers click "Create pull request": + +.. code-block:: console + + ## Description of changes + Provide a description of what this PR does. What bug does it fix, or what feature does it add? Do you expect that this PR will change answers, and if so, under what circumstances? If this PR is for a physics innovation, please provide references to any relevant scientific papers. + + ## Issues addressed (optional) + If this PR addresses one or more issues, please provide link(s) to the issue(s) here. + - fixes hafs-community/HAFS/issues/ + + ## Dependencies (optional) + If submodule PRs are required, please link them below. For example: + - hafs-community/ufs-weather-model/pull/ + - hafs-community/UPP/pull/ + - hafs-community/UFS_UTILS/pull/ + - hafs-community/GSI/pull/ + + ## Contributors (optional) + If others worked on this PR besides the author, please include their user names here (using @Mention if possible). + + ## Tests conducted + What testing has been conducted on the PR thus far? Describe the nature of any scientific or technical tests, including relevant details about the configuration(s) (e.g., cold versus warm start, number of cycles, forecast length, whether data assimilation was performed, etc). What platform(s) were used for testing? + + ## Application-level regression test status + Running the HAFS application-level regression tests is currently performed by code reviewers after the developer creates the initial PR. As regression tests are conducted, the testers should use the checklist below to indicate **successful** regression tests. You may add other tests as needed. If a test fails, do not check the box. Instead, describe the failure in the PR comments, noting the platform where the test failed. + + - [ ] Jet + - [ ] Hera + - [ ] Orion + - [ ] WCOSS2 + +Merging +======== + +Your PR is ready to merge when: + +#. It has been approved by a required number of HAFS reviewers, including at least one reviewer with write permissions. +#. All conversations have been marked as resolved. +#. Regression tests have passed on all supported platforms. + +These criteria and their current statuses are detailed in a section at the bottom of your PR's *Conversation* tab. Checks take some time to run, so please be patient. + +Need Help? +=========== + +For assistance directly related to a PR, please use comments in the *Conversation* tab of your PR to ask for help with any difficulties you encounter! diff --git a/doc/UsersGuide/source/ContributorsGuide/index.rst b/doc/UsersGuide/source/ContributorsGuide/index.rst new file mode 100644 index 000000000..7b12e2f1f --- /dev/null +++ b/doc/UsersGuide/source/ContributorsGuide/index.rst @@ -0,0 +1,8 @@ +Contributor's Guide +======================================================== + +.. toctree:: + :maxdepth: 3 + + GitHubBasicSteps + HAFSCodeContributionGuidelines \ No newline at end of file diff --git a/docs/UsersGuide/source/CDEPS.rst b/doc/UsersGuide/source/CustomizingTheWorkflow/CDEPS.rst similarity index 98% rename from docs/UsersGuide/source/CDEPS.rst rename to doc/UsersGuide/source/CustomizingTheWorkflow/CDEPS.rst index 474a5275a..18fe5bf17 100644 --- a/docs/UsersGuide/source/CDEPS.rst +++ b/doc/UsersGuide/source/CustomizingTheWorkflow/CDEPS.rst @@ -80,7 +80,7 @@ The DAPP keyword in the call to ``./compile.sh`` in ``./sorc/build_forecast.sh`` By default, the DAPP keyword should already be set to HAFS-ALL on all supported machines except wcoss_cray. -The remainder of the build process is the same as described in the :ref:`HAFS installation guide `. +The remainder of the build process is the same as described in the :ref:`HAFS Quick Start Guide `. ================================ Using CDEPS in the HAFS Workflow @@ -177,7 +177,7 @@ Appendix A: HAFS-CDEPS Configuration Options The following table describes variables that are relevant to the HAFS-CDEPS configuration, along with some recommendations for setting them. The recommended settings have already been applied in the various configuration files. .. csv-table:: HAFS-CDEPS Configuration Options - :file: tables/hafs_cdeps_config.csv + :file: ../tables/hafs_cdeps_config.csv :widths: auto :header-rows: 1 @@ -209,14 +209,14 @@ While it is impossible to formally support every dataset in HAFS-CDEPS, develope #. For a run that couples DATM to HYCOM, the variables that must be present in your input dataset (along with the expected units) are as follows: .. csv-table:: Required Input Variable(s) for DATM to HYCOM - :file: tables/input_vars_datm.csv + :file: ../tables/input_vars_datm.csv :widths: auto :header-rows: 1 For a run that couples DOCN to the UFS Weather Model, the only variable that must be present in your input dataset (along with the expected unit) is as follows: .. csv-table:: Required Input Variable(s) for DOCN to UFS Weather Model - :file: tables/input_vars_docn.csv + :file: ../tables/input_vars_docn.csv :widths: auto :header-rows: 1 @@ -226,5 +226,5 @@ While it is impossible to formally support every dataset in HAFS-CDEPS, develope .. rubric:: Footnotes .. [#] https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels -.. [#] https://www.ncdc.noaa.gov/oisst/optimum-interpolation-sea-surface-temperature-oisst-v21 +.. [#] https://www.ncei.noaa.gov/products/optimum-interpolation-sst .. [#] https://www.ghrsst.org/about-ghrsst/overview/ diff --git a/doc/UsersGuide/source/CustomizingTheWorkflow/index.rst b/doc/UsersGuide/source/CustomizingTheWorkflow/index.rst new file mode 100644 index 000000000..85e6142f7 --- /dev/null +++ b/doc/UsersGuide/source/CustomizingTheWorkflow/index.rst @@ -0,0 +1,16 @@ +Customizing The Workflow +======================================================== + +.. toctree:: + :maxdepth: 3 + + CDEPS + + + + + + + + + diff --git a/docs/UsersGuide/source/Glossary.rst b/doc/UsersGuide/source/Reference/Glossary.rst similarity index 100% rename from docs/UsersGuide/source/Glossary.rst rename to doc/UsersGuide/source/Reference/Glossary.rst diff --git a/doc/UsersGuide/source/Reference/ReferenceMaterials.rst b/doc/UsersGuide/source/Reference/ReferenceMaterials.rst new file mode 100644 index 000000000..ca5c3a288 --- /dev/null +++ b/doc/UsersGuide/source/Reference/ReferenceMaterials.rst @@ -0,0 +1,71 @@ +.. _ReferenceMaterials: + +******************** +Reference Materials +******************** + +This chapter provides a collection of reference materials, including guidance documents +(e.g., NCEP Implementation Standards), code management documents, and other useful resources. + +.. _GuidanceDocs: + +=================== +Guidance Documents +=================== + +- `NCO Implementation Standards `__ +- `NCEP EE2 Consolidated Document `__ * +- `Code Management of Repositories Under EMC Management Using GitFlow `__ * + +\* Requires NOAA email for access + +.. _CodeManagement: + +========================================= +Useful Code Management Related Materials +========================================= + +- `UFS Github Repository Code Management `_ * +- `Versioning for UFS Repositories `_ +- :ref:`Contributing to HAFS ` +- More about GitFlow: + + - `A Successful Git Branching Model `_ by Vincent Driessen + - `GitFlow at GitHub `_ + - `GitFlow Examples `_ from GitVersion + +\* Requires NOAA email for access + +.. _UsefulResources: + +================= +Useful Resources +================= + +- GFS `global-workflow repository `_, `wiki `_, and `documentation `_ +- `UFS Weather Model User's Guide `__ +- Common Community Physics Package (CCPP): + + - `CCPP Technical Documentation (User’s Guide) `_ + - `CCPP Scientific Documentation `_ + +- `UFS_UTILS repository `_ + + - `UFS_UTILS User’s Guide `_ + - `UFS_UTILS Scientific Documentation `_ + +- `UFS Short-Range Weather App User's Guide `_ +- `UPP repository `_ (formerly *EMC_post*) + + - `UPP User’s Guide Documentation `_ + - `UPP Scientific Documentation `_ + +- `FV3 multinest presentation from GFDL `__ * +- JCSDA JEDI Academy Slides: `Nov 2020 Academy Slides `__ +- `JEDI Documentation `__ +- About Rocoto Workflow Management: `GitHub repository `__ and `documentation `__ +- `Some Git How-Tos `__ * +- `Configuring Git for Multiple GitHub Accounts `__ (this information may be useful for users with multiple GitHub accounts for configuring where Git pushes your commits) +- `EIB Seminar CMake presentation `__ * + +\* Requires NOAA email for access diff --git a/doc/UsersGuide/source/Reference/index.rst b/doc/UsersGuide/source/Reference/index.rst new file mode 100644 index 000000000..0f1799dfe --- /dev/null +++ b/doc/UsersGuide/source/Reference/index.rst @@ -0,0 +1,8 @@ +Reference +======================================================== + +.. toctree:: + :maxdepth: 3 + + ReferenceMaterials + Glossary \ No newline at end of file diff --git a/docs/UsersGuide/source/_static/README b/doc/UsersGuide/source/_static/README similarity index 100% rename from docs/UsersGuide/source/_static/README rename to doc/UsersGuide/source/_static/README diff --git a/doc/UsersGuide/source/_static/custom.css b/doc/UsersGuide/source/_static/custom.css new file mode 100644 index 000000000..c02df7fed --- /dev/null +++ b/doc/UsersGuide/source/_static/custom.css @@ -0,0 +1,25 @@ +.red { color: red; } +.bolditalic { + font-family: "Courier New", Courier, monospace; + font-weight: bold; + font-style: italic; +} + +.underline { + text-decoration: underline; +} + +.bolditalic { + font-weight: bold; + font-style: italic; +} + +table.align-default { + margin-left: 0px; + margin-right: auto; +} + +table.align-center { + margin-left: 0px; + margin-right: auto; +} diff --git a/doc/UsersGuide/source/_static/theme_overrides.css b/doc/UsersGuide/source/_static/theme_overrides.css new file mode 100644 index 000000000..ca4ac9254 --- /dev/null +++ b/doc/UsersGuide/source/_static/theme_overrides.css @@ -0,0 +1,24 @@ +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-nav-content { + max-width: 100% !important; + } + + /* .wy-table-responsive { */ + /* overflow: visible !important; */ + /* } */ + + } + + /* Darken navbar blue background for contrast with logo */ + .wy-side-nav-search, .wy-nav-top { + background: #2779B0; + } + \ No newline at end of file diff --git a/docs/UsersGuide/source/_templates/README b/doc/UsersGuide/source/_templates/README similarity index 100% rename from docs/UsersGuide/source/_templates/README rename to doc/UsersGuide/source/_templates/README diff --git a/docs/UsersGuide/source/conf.py b/doc/UsersGuide/source/conf.py similarity index 74% rename from docs/UsersGuide/source/conf.py rename to doc/UsersGuide/source/conf.py index 695645536..c2cc38dd5 100644 --- a/docs/UsersGuide/source/conf.py +++ b/doc/UsersGuide/source/conf.py @@ -24,9 +24,9 @@ author = ' ' # The short X.Y version -version = '' +version = 'develop' # The full version, including alpha/beta/rc tags -release = '' +release = 'Develop Branch Documentation' numfig = True @@ -41,10 +41,11 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx_rtd_theme', 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', + 'sphinx.ext.extlinks', 'sphinx.ext.coverage', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', @@ -73,7 +74,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -81,22 +82,35 @@ exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = None +pygments_style = 'sphinx' +#Ignore working links that cause a linkcheck 403 error +linkcheck_ignore = [ + r'https://docs.google.com/*', + r'https://drive.google.com/*', +] + +linkcheck_allowed_redirects = {r"https://github\.com/hafs-community/HAFS/wiki/.*": + r"https://raw\.githubusercontent\.com/wiki/hafs-community/HAFS/.*", + r"https://github.com/hafs-community/HAFS/*/*": + r"https://github.com/login*", + } # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'classic' +html_theme = 'sphinx_rtd_theme' +html_theme_path = ["_themes", ] # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # -# html_theme_options = {} -html_theme_options = {"body_max_width": "none"} +html_theme_options = {"body_max_width": "none", + "navigation_depth": 6, + } # html_sidebar_options = {} html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] } @@ -105,9 +119,11 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] +html_context = {} def setup(app): app.add_css_file('custom.css') # may also be an URL + app.add_css_file('theme_overrides.css') # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -131,15 +147,17 @@ def setup(app): latex_engine = 'pdflatex' latex_elements = { # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - + 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - + 'pointsize': '11pt', # Additional stuff for the LaTeX preamble. - # + 'preamble': r''' + \usepackage{charter} + \usepackage[defaultsans]{lato} + \usepackage{inconsolata} + ''', + # 'preamble': '', # Latex figure (float) alignment @@ -162,7 +180,7 @@ def setup(app): # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'HAFS_Users_Guide', 'HAFS Users Guide', + (master_doc, 'HAFS', "HAFS User's Guide", [author], 1) ] @@ -173,9 +191,9 @@ def setup(app): # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'HAFS_Users_guide', 'HAFS Users Guide', - author, 'HAFS_Users_Guide', 'One line description of project.', - 'Miscellaneous'), + (master_doc, 'HAFS', "HAFS User's Guide", + author, 'HAFS', 'One line description of project.', + 'Miscellaneous'),'' ] @@ -202,9 +220,16 @@ def setup(app): # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} - -# -- Options for todo extension ---------------------------------------------- - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True +intersphinx_mapping = {'python': ('https://docs.python.org/3', None), + } + +# -- Options for extlinks extension --------------------------------------- + +extlinks_detect_hardcoded_links = True +extlinks = {'github-docs': ('https://docs.github.com/en/%s', '%s'), + 'nco': ('https://www.nco.ncep.noaa.gov/idsb/implementation_standards/%s', '%s'), + 'hafs-repo': ('https://github.com/hafs-community/HAFS/%s', '%s'), + 'hafs-wiki': ('https://github.com/hafs-community/HAFS/wiki/%s','%s'), + 'uw': ('https://uwtools.readthedocs.io/en/main/%s', '%s'), + 'wm': ('https://ufs-weather-model.readthedocs.io/en/develop/%s', '%s'), + } diff --git a/doc/UsersGuide/source/index.rst b/doc/UsersGuide/source/index.rst new file mode 100644 index 000000000..bb62862d5 --- /dev/null +++ b/doc/UsersGuide/source/index.rst @@ -0,0 +1,12 @@ +HAFS User's Guide (|version|) +======================================================== + +.. toctree:: + :numbered: + :maxdepth: 3 + + Backgroundinfo/index + BuildingRunningTesting/index + CustomizingTheWorkflow/index + ContributorsGuide/index + Reference/index \ No newline at end of file diff --git a/docs/UsersGuide/source/references.bib b/doc/UsersGuide/source/references.bib similarity index 100% rename from docs/UsersGuide/source/references.bib rename to doc/UsersGuide/source/references.bib diff --git a/docs/UsersGuide/source/tables/hafs_cdeps_config.csv b/doc/UsersGuide/source/tables/hafs_cdeps_config.csv similarity index 99% rename from docs/UsersGuide/source/tables/hafs_cdeps_config.csv rename to doc/UsersGuide/source/tables/hafs_cdeps_config.csv index d973eb1ba..b682dd77f 100644 --- a/docs/UsersGuide/source/tables/hafs_cdeps_config.csv +++ b/doc/UsersGuide/source/tables/hafs_cdeps_config.csv @@ -1,35 +1,35 @@ -Section,Variable name,Description,Valid Values -[config],,, -,run_datm,Whether to run data atmosphere (:term:`DATM`), ``yes`` | ``no`` -,run_docn,Whether to run data ocean (:term:`DOCN`),``yes`` | ``no`` -,run_ocean,Whether to run the active ocean model. Must be no if ``run_docn=yes``,``yes`` | ``no`` -,run_dwav,Whether to run data wave (:term:`DWAV`),not yet implemented -,make_mesh_atm,Whether the workflow should generate a mesh file that describes the grid for DATM. Unless the user is providing a custom mesh file this should be set to yes. No effect if ``run_datm=no``.,``yes`` | ``no`` -,mesh_atm_in,The location of the premade DATM mesh file. Only used if ``run_datm=yes`` and ``make_mesh_atm=no``,*file path* -,make_mesh_ocn,Whether the workflow should generate a mesh file that describes the grid for DOCN. Unless the user is providing a custom mesh file this should be set to yes. No effect if ``run_docn=no``.,``yes`` | ``no`` -,mesh_ocn_in,The location of the premade DOCN mesh file. Only used if ``run_docn=yes`` and ``make_mesh_ocn=no``.,*file path* -,datm_source,The data source used for DATM. Only ERA5 is supported. No effect if ``run_datm=no``.,``era5`` -,DATMdir,The location where DATM input data are staged by the user. This variable is set in ``system.conf.[machine]``. The workflow will not download new data if the necessary input files are already present in ``DATMdir``.,*file path* -,docn_source,The data source used for DOCN. Only OISST and GHRSST are supported. No effect if ``run_docn=no``.,``oisst`` | ``ghrsst`` -,DOCNdir,The location where DOCN input data are staged by the user. This variable is set in ``system.conf.[machine]``. The workflow will not download new data if the necessary input files are already present in ``DOCNdir``.,*file path* -,scrub_com,Whether to scrub the cycle’s ``com`` directory at the end of the run. Recommend setting to no to avoid losing files generated by CDEPS that the archive job does not save.,``yes`` | ``no`` -,scrub_work,Whether to scrub the cycle’s ``work`` directory at the end of the run. Recommend setting to no to avoid losing files generated by CDEPS that the archive job does not save.,``yes`` | ``no`` -,run_vortexinit,Whether to run the vortex initialization. Must be no if ``run_datm=yes``.,``yes`` | ``no`` -,run_gsi_vr,Whether to run the GSI-based vortex relocation. Must be no if ``run_datm=yes``.,``yes`` | ``no`` -,run_gsi_vr_fgat,Whether to run the GSI-based vortex relocation with :term:`FGAT`. Must be no if ``run_datm=yes``.,``yes`` | ``no`` -,run_gsi_vr_ens,Whether to run the GSI-based vortex relocation for each HAFS ensemble member. Must be no if ``run_datm=yes``.,``yes`` | ``no`` -,run_gsi,Whether to run data assimilation with GSI. Must be no if ``run_datm=yes``.,``yes`` | ``no`` -,run_fgat,Whether to run data assimilation using FGAT. Must be no if ``run_datm=yes``.,``yes`` | ``no`` -,run_envar,Whether to run hybrid EnVar data assimilation. Must be no if ``run_datm=yes``.,``yes`` | ``no`` -,run_ensda,Whether to run the HAFS ensemble. Must be no if ``run_datm=yes``.,``yes`` | ``no`` -,run_enkf,Whether to run the EnKF analysis step. Must be no if ``run_datm=yes``.,``yes`` | ``no`` -[forecast],, -,layoutx,Processor decomposition in the x-direction.,  -,layouty,Processor decomposition in the y-direction., -,write_groups,Number of processor groups for I/O.,*integer >= 1* -,write_tasks_per_group,Number of cores per I/O group.,*integer >= 1* -,ocean_tasks,Number of cores for the ocean model.,*integer >= 1* -,docn_mesh_nx_global,DOCN domain size in the x-direction.,*integer >= 1* -,docn_mesh_ny_global,DOCN domain size in the y-direction.,*integer >= 1* -[rocotostr],,, +Section,Variable name,Description,Valid Values +[config],,, +,run_datm,Whether to run data atmosphere (:term:`DATM`), ``yes`` | ``no`` +,run_docn,Whether to run data ocean (:term:`DOCN`),``yes`` | ``no`` +,run_ocean,Whether to run the active ocean model. Must be no if ``run_docn=yes``,``yes`` | ``no`` +,run_dwav,Whether to run data wave (:term:`DWAV`),not yet implemented +,make_mesh_atm,Whether the workflow should generate a mesh file that describes the grid for DATM. Unless the user is providing a custom mesh file this should be set to yes. No effect if ``run_datm=no``.,``yes`` | ``no`` +,mesh_atm_in,The location of the premade DATM mesh file. Only used if ``run_datm=yes`` and ``make_mesh_atm=no``,*file path* +,make_mesh_ocn,Whether the workflow should generate a mesh file that describes the grid for DOCN. Unless the user is providing a custom mesh file this should be set to yes. No effect if ``run_docn=no``.,``yes`` | ``no`` +,mesh_ocn_in,The location of the premade DOCN mesh file. Only used if ``run_docn=yes`` and ``make_mesh_ocn=no``.,*file path* +,datm_source,The data source used for DATM. Only ERA5 is supported. No effect if ``run_datm=no``.,``era5`` +,DATMdir,The location where DATM input data are staged by the user. This variable is set in ``system.conf.[machine]``. The workflow will not download new data if the necessary input files are already present in ``DATMdir``.,*file path* +,docn_source,The data source used for DOCN. Only OISST and GHRSST are supported. No effect if ``run_docn=no``.,``oisst`` | ``ghrsst`` +,DOCNdir,The location where DOCN input data are staged by the user. This variable is set in ``system.conf.[machine]``. The workflow will not download new data if the necessary input files are already present in ``DOCNdir``.,*file path* +,scrub_com,Whether to scrub the cycle’s ``com`` directory at the end of the run. Recommend setting to no to avoid losing files generated by CDEPS that the archive job does not save.,``yes`` | ``no`` +,scrub_work,Whether to scrub the cycle’s ``work`` directory at the end of the run. Recommend setting to no to avoid losing files generated by CDEPS that the archive job does not save.,``yes`` | ``no`` +,run_vortexinit,Whether to run the vortex initialization. Must be no if ``run_datm=yes``.,``yes`` | ``no`` +,run_gsi_vr,Whether to run the GSI-based vortex relocation. Must be no if ``run_datm=yes``.,``yes`` | ``no`` +,run_gsi_vr_fgat,Whether to run the GSI-based vortex relocation with :term:`FGAT`. Must be no if ``run_datm=yes``.,``yes`` | ``no`` +,run_gsi_vr_ens,Whether to run the GSI-based vortex relocation for each HAFS ensemble member. Must be no if ``run_datm=yes``.,``yes`` | ``no`` +,run_gsi,Whether to run data assimilation with GSI. Must be no if ``run_datm=yes``.,``yes`` | ``no`` +,run_fgat,Whether to run data assimilation using FGAT. Must be no if ``run_datm=yes``.,``yes`` | ``no`` +,run_envar,Whether to run hybrid EnVar data assimilation. Must be no if ``run_datm=yes``.,``yes`` | ``no`` +,run_ensda,Whether to run the HAFS ensemble. Must be no if ``run_datm=yes``.,``yes`` | ``no`` +,run_enkf,Whether to run the EnKF analysis step. Must be no if ``run_datm=yes``.,``yes`` | ``no`` +[forecast],, +,layoutx,Processor decomposition in the x-direction.,  +,layouty,Processor decomposition in the y-direction., +,write_groups,Number of processor groups for I/O.,*integer >= 1* +,write_tasks_per_group,Number of cores per I/O group.,*integer >= 1* +,ocean_tasks,Number of cores for the ocean model.,*integer >= 1* +,docn_mesh_nx_global,DOCN domain size in the x-direction.,*integer >= 1* +,docn_mesh_ny_global,DOCN domain size in the y-direction.,*integer >= 1* +[rocotostr],,, ,FORECAST_RESOURCES,String that describes the forecast resources. It must match an entry in the file for your platform in ``./rocoto/sites/``., \ No newline at end of file diff --git a/docs/UsersGuide/source/tables/input_vars_datm.csv b/doc/UsersGuide/source/tables/input_vars_datm.csv similarity index 98% rename from docs/UsersGuide/source/tables/input_vars_datm.csv rename to doc/UsersGuide/source/tables/input_vars_datm.csv index 01d5fc2bb..023e2faed 100644 --- a/docs/UsersGuide/source/tables/input_vars_datm.csv +++ b/doc/UsersGuide/source/tables/input_vars_datm.csv @@ -1,9 +1,9 @@ -CDEPS DATM variable,Unit,Description -Sa_pslv,Pa,Mean sea-level pressure -Faxa_rain,m,Liquid-equivalent total precipitation -Faxa_swnet,J m\ :sup:`2`,Surface net downward shortwave flux -Faxa_lwnet,J m\ :sup:`2`,Surface net upwelling longwave flux -Faxa_sen,J m\ :sup:`2`,Surface upward sensible heat flux -Faxa_lat,J m\ :sup:`2`,Surface upward latent heat flux -Faxa_taux,N m\ :sup:`2` s,Surface zonal-component turbulent stress +CDEPS DATM variable,Unit,Description +Sa_pslv,Pa,Mean sea-level pressure +Faxa_rain,m,Liquid-equivalent total precipitation +Faxa_swnet,J m\ :sup:`2`,Surface net downward shortwave flux +Faxa_lwnet,J m\ :sup:`2`,Surface net upwelling longwave flux +Faxa_sen,J m\ :sup:`2`,Surface upward sensible heat flux +Faxa_lat,J m\ :sup:`2`,Surface upward latent heat flux +Faxa_taux,N m\ :sup:`2` s,Surface zonal-component turbulent stress Faxa_tauy,N m\ :sup:`2` s,Surface meridional-component turbulent stress \ No newline at end of file diff --git a/docs/UsersGuide/source/tables/input_vars_docn.csv b/doc/UsersGuide/source/tables/input_vars_docn.csv similarity index 98% rename from docs/UsersGuide/source/tables/input_vars_docn.csv rename to doc/UsersGuide/source/tables/input_vars_docn.csv index 65e9fe979..1d212efd3 100644 --- a/docs/UsersGuide/source/tables/input_vars_docn.csv +++ b/doc/UsersGuide/source/tables/input_vars_docn.csv @@ -1,2 +1,2 @@ -CDEPS DOCN variable,Unit,Description +CDEPS DOCN variable,Unit,Description So_t,℃,Sea-surface temperature \ No newline at end of file diff --git a/docs/UsersGuide/build/.gitignore b/docs/UsersGuide/build/.gitignore deleted file mode 100644 index 0addfc818..000000000 --- a/docs/UsersGuide/build/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -# Ignore everything in this directory -* -# Except this file -!.gitignore diff --git a/docs/UsersGuide/requirements.txt b/docs/UsersGuide/requirements.txt deleted file mode 100644 index ef36addc6..000000000 --- a/docs/UsersGuide/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -sphinxcontrib-bibtex diff --git a/docs/UsersGuide/source/ReferenceMaterials.rst b/docs/UsersGuide/source/ReferenceMaterials.rst deleted file mode 100644 index 12ed2d9d5..000000000 --- a/docs/UsersGuide/source/ReferenceMaterials.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. _ReferenceMaterials: - -******************** -Reference Materials -******************** - -This chapter provides a collection of reference materials, including guidance documents -(e.g., NCEP Implementation Standards), code management documents, and other useful resources. - -.. _GuidanceDocs: - -=================== -Guidance Documents -=================== - -- `NCO Implementation Standards `__ -- `Recommendation for Adoption of NCEP EE2 Process Document `__ * -- `Code Management of Repositories Under EMC Management Using GitFlow `__ * -- `EMC Github Repository Code Management `__ * - -\* Requires NOAA email for access - -.. _CodeManagement: - -========================================= -Useful Code Management Related Materials -========================================= - -- `UFS Github Repository Code Management `__ * -- `Versioning for UFS Repositories `__ * -- `Making Code Changes in GitHub UFS Forecast Model Repository `__ * -- `ufs-weather-model Development Training Presentation `__ * -- `GitHub at EMC Presentation `__ * -- More about GitFlow: - - - `A Successful Git Branching Model `__ by Vincent Driessen - - `GitFlow at GitHub `__ - - `GitFlow Examples `__ from GitVersion - -\* Requires NOAA email for access - -.. _UsefulResources: - -================= -Useful Resources -================= - -- GFS global-workflow GitHub `repository `__ and `wiki `__ -- `UFS Weather Model User's Guide `__ -- `CCPP Scientific Documentation `__ -- UFS-UTILS `repository `__ and `chgres_cube documentation `__ - - - `chgres_cube introduction presentation `__ * - -- `UFS Short-Range Weather App User's Guide `__ -- :term:`UPP` `repository `__ (formerly *EMC_post*) - - - `UPP Documentation `__ - -- `FV3 multinest presentation from GFDL `__ * -- JCSDA JEDI Academy Slides: `Nov 2020 Academy Slides `__ -- `JEDI Documentation `__ -- About Rocoto Workflow Management: `GitHub repository `__ and `documentation `__ -- `Some Git How-Tos `__ * -- `Configuring Git for Multiple GitHub Accounts `__ (this information may be useful for users with multiple GitHub accounts for configuring where Git pushes your commits) -- `EIB Seminar CMake presentation `__ * - -\* Requires NOAA email for access diff --git a/docs/UsersGuide/source/_static/custom.css b/docs/UsersGuide/source/_static/custom.css deleted file mode 100644 index b4f1e2219..000000000 --- a/docs/UsersGuide/source/_static/custom.css +++ /dev/null @@ -1,28 +0,0 @@ -@import "default.css"; - -div.admonition-todo { -border-top: 2px solid red; -border-bottom: 2px solid red; -border-left: 2px solid red; -border-right: 2px solid red; -background-color: #ff6347 -} - -p.admonition-title { - display: offline; -} - -/*p.first.admonition-title { -background-color: #aa6347; -width: 100%; -} -*/ - -.underline { - text-decoration: underline; -} - -.bolditalic { - font-weight: bold; - font-style: italic; -} diff --git a/docs/UsersGuide/source/index.rst b/docs/UsersGuide/source/index.rst deleted file mode 100644 index 8bb7950dc..000000000 --- a/docs/UsersGuide/source/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. HAFS Users Guide, created by - sphinx-quickstart on Fri Nov 05 10:00:00 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to the HAFS User's Guide -======================================================== - -.. toctree:: - :numbered: - :maxdepth: 3 - - Introduction - TechnicalOverview - QuickStart - ExtQuickStart - GitHubBasicSteps - RegressionTest - CDEPS - ReferenceMaterials - Glossary