Text/us 64

.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
+    - requirements: doc/UsersGuide/requirements.txt

docs/UsersGuide/Makefile → 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

docs/UsersGuide/make.bat → 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

doc/UsersGuide/requirements.in

@@ -0,0 +1,3 @@
+sphinx>=6.0.0
+sphinx_rtd_theme
+sphinxcontrib-bibtex

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

docs/UsersGuide/source/Introduction.rst → 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 <https://github.com/hafs-community/HAFS/wiki/HAFS-Code-Repository-Governance>`__.
+For information about how to contribute to HAFS development, please review the :hafs-wiki:`code repository governance <HAFS-Code-Repository-Governance>`.
 
 The HAFS repository is located at `<https://github.com/hafs-community/HAFS>`__.

doc/UsersGuide/source/Backgroundinfo/index.rst

@@ -0,0 +1,9 @@
+Background Information
+========================================================
+
+.. toctree::
+   :maxdepth: 3
+
+   Introduction
+   TechnicalOverview
+

doc/UsersGuide/source/BuildingRunningTesting/index.rst

@@ -0,0 +1,9 @@
+Building, Running, and Testing HAFS
+========================================================
+
+.. toctree::
+   :maxdepth: 3
+
+   QuickStart
+   ExtQuickStart
+   RegressionTest

docs/UsersGuide/source/GitHubBasicSteps.rst → 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 <https://guides.github.com/activities/forking/>`__
+   .. hint:: See `GitHub forking projects <https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project>`__
 
 ====================================================
 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``.