[develop]: Update documentation to reflect recent (Feb '24) changes (#72

)

* add extlinks & UFS/EPIC logo

* add linkcheck to doc Makefile

* add/update requirements files

* update linkcheck redirects/ignores

* update tech overview; minor conf.py edits

* reorganize/add to Tech Overview

* rm comments

* update build/run ch w/config info

* update configuration/run/status check info in build/run ch

* move info on data

* minor edits

* update BASEDIR path in land_analysis.yaml

* add FAQ; rm info on log/err files from build/run ch

* change docs to doc

* update Glossary, uwtools desc; misc

* update RTD YAML

* minor fix to FAQ

* update LANDDAROOT path

* minor edits from chj

* add run w/o rocot info & jjobs info

* update auto_doc.yaml to use doc instead of docs

* update dir structure

* add NCEP/NCO terms

* update UW tools link

* complete sentence

* update dir str diagram

* update log file info and com dir str diagram

* minor build/run updates

* add RTD integration to repo?

.github/workflows/auto_doc.yml

@@ -20,11 +20,11 @@ jobs:
       uses: actions/upload-artifact@v3
       with:
         name: html-docs
-        path: docs/build/html/
+        path: doc/build/html/
 
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3
       if: github.ref == 'refs/heads/develop'
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: docs/build/html/
+        publish_dir: doc/build/html/

.readthedocs.yaml

@@ -17,7 +17,7 @@ build:
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: docs/source/conf.py
+   configuration: doc/source/conf.py
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
 # formats:
@@ -26,6 +26,6 @@ sphinx:
 # Optionally declare the Python requirements required to build your docs
 python:
    install:
-   - requirements: docs/requirements.txt
+   - requirements: doc/requirements.txt
 
 

docs/Makefile → doc/Makefile

@@ -3,18 +3,30 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    = -a -n #-W
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
+LINKCHECKDIR  = $(BUILDDIR)/linkcheck
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile linkcheck
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+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/make.bat → doc/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
-
-%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.https://www.sphinx-doc.org/
-	exit /b 1
-)
-
-if "%1" == "" goto help
-
-%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
+
+%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.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt → doc/requirements.in

@@ -1,4 +1,3 @@
-sphinxcontrib-bibtex
+sphinx>=6.0.0
 sphinx_rtd_theme
-docutils>=0.18.1
-urllib3==1.26.15
+sphinxcontrib-bibtex

doc/requirements.txt

@@ -0,0 +1,76 @@
+#
+# 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
+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==1.26.15
+    # via requests

docs/source/BackgroundInfo/Introduction.rst → doc/source/BackgroundInfo/Introduction.rst

@@ -80,7 +80,7 @@ When posting a question, it is recommended that users provide the following info
 Bug Reports
 ============
 
-If users (especially new users) believe they have identified a bug in the system, it is recommended that they first ask about the problem in `GitHub Discussions <https://github.com/ufs-community/land-DA_workflow/discussions/categories/q-a>`__, since many "bugs" do not require a code change/fix --- instead, the user may be unfamiliar with the system and/or may have misunderstood some component of the system or the instructions, which is causing the problem. Asking for assistance in a `GitHub Discussion <https://github.com/ufs-community/land-DA_workflow/discussions/categories/q-a>`__ post can help clarify whether there is a simple adjustment to fix the problem or whether there is a genuine bug in the code. Users are also encouraged to search `open issues <https://github.com/ufs-community/land-DA_workflow/issues>`__ to see if their bug has already been identified. If there is a genuine bug, and there is no open issue to address it, users can report the bug by filing a `GitHub Issue <https://github.com/ufs-community/land-DA_workflow/issues/new>`__. 
+If users (especially new users) believe they have identified a bug in the system, it is recommended that they first ask about the problem in :land-wflow-repo:`GitHub Discussions <discussions/categories/q-a>`, since many "bugs" do not require a code change/fix --- instead, the user may be unfamiliar with the system and/or may have misunderstood some component of the system or the instructions, which is causing the problem. Asking for assistance in a :land-wflow-repo:`GitHub Discussion <discussions/categories/q-a>` post can help clarify whether there is a simple adjustment to fix the problem or whether there is a genuine bug in the code. Users are also encouraged to search :land-wflow-repo:`open issues <issues>` to see if their bug has already been identified. If there is a genuine bug, and there is no open issue to address it, users can report the bug by filing a :land-wflow-repo:`GitHub Issue <issues/new>`. 
 
 Feature Requests and Enhancements
 ==================================