Add Sphinx version of User Guide for ReadTheDocs

Add Open-Source tools info
Add Crocus documentation, clean up citation

.gitignore

@@ -27,4 +27,5 @@ README.md
 *.log
 compile_options.sh
 .DS_Store
+.venv
 .vscode

.readthedocs.yaml

@@ -0,0 +1,35 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/userguide/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

docs/requirements.txt

@@ -0,0 +1 @@
+sphinx_rtd_theme

docs/userguide/_static/ug_theme.css

@@ -0,0 +1,29 @@
+.wy-nav-content {
+    max-width: 1000px !important;
+}
+
+.center {
+    text-align: center;
+}
+
+.underline {
+    text-decoration: underline;
+}
+
+.filename {
+    font-family: Courier, "Courier New", monospace;
+    white-space: pre-wrap;
+}
+
+.program {
+    font-family: Courier, "Courier New", monospace;
+    white-space: pre-wrap;
+    color: greenyellow;
+    background-color: black;
+    padding-left: 5px;
+    padding-right: 5px;
+}
+
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}

docs/userguide/conf.py

@@ -0,0 +1,32 @@
+project = 'WRF-Hydro Modeling System'
+author = 'WRF-Hydro Team'
+copyright = '2024, '+author
+version = 'v5.4.0'
+release = '5.4.0'
+try:
+    import sphinx_rtd_theme
+    extensions = [
+        'sphinx_rtd_theme',
+    ]
+    # html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_options = {
+        'navigation_depth': -1
+    }
+except:
+    pass
+html_static_path = ['_static']
+html_css_files = ['ug_theme.css']
+numfig_secnum_depth = 2
+
+#these are enforced by rstdoc, but keep them for sphinx-build
+numfig = 0
+smartquotes = 0
+source_suffix = '.rest'
+templates_path = []
+language = 'en'
+highlight_language = "none"
+default_role = 'math'
+pygments_style = 'sphinx'
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+master_doc = 'index'

docs/userguide/index.rest

@@ -0,0 +1,113 @@
+.. vim: syntax=rst
+.. include:: meta.rest
+
+.. image:: media/wrfhydro-banner.png
+    :align: center
+
+=========================================================
+The NCAR WRF-Hydro® Modeling System Technical Description
+=========================================================
+.. rst-class:: center
+
+    | Version |version_long|
+    |
+    | Originally Created:
+    | April 14, 2013
+    |
+    | Updated:
+    | October 17, 2024
+
+Until further notice, please cite the WRF-Hydro® modeling system as
+follows:
+
+Gochis, D.J., M. Barlage, R. Cabell, M. Casali, A. Dugger, T. Eidhammer,
+K. FitzGerald, M. McAllister, J. McCreight, A. McCluskey, A. RafieeiNasab,
+S. Rasmussen, L. Read, K. Sampson, D. Yates, Y. Zhang (2024).
+*The WRF-Hydro® Modeling System Technical Description,* (Version 5.4).
+NCAR Technical Note. 107 pages. Available online at:
+https://wrf-hydro.readthedocs.io/en/latest/
+
+.. rubric:: FORWARD
+
+This Technical Description describes the WRF-Hydro® model coupling
+architecture and physics options, released in Version 5.4 in Oct. 2024.
+As the WRF-Hydro® modeling system is developed further, this document
+will be continuously enhanced and updated. Please send feedback to
+[email protected].
+
+.. rubric:: Prepared by:
+
+David Gochis, Michael Barlage, Ryan Cabell, Matt Casali, Aubrey Dugger, Trude
+Eidhammer, Katelyn FitzGerald, Molly McAllister, James McCreight, Alyssa
+McCluskey, Arezoo RafieeiNasab, Soren Rasmussen, Laura Read, Kevin Sampson,
+David Yates, and Yongxin Zhang
+
+.. rubric:: Special Acknowledgments:
+
+Development of the NCAR WRF-Hydro system has been significantly enhanced
+through numerous collaborations. The following persons are graciously
+thanked for their contributions to this effort:
+
+John McHenry and Carlie Coats, Baron Advanced Meteorological Services
+
+Martyn Clark and Fei Chen, National Center for Atmospheric Research
+
+Zong-Liang Yang, Cedric David, Peirong Lin and David Maidment of the
+University of Texas at Austin
+
+Harald Kunstmann, Benjamin Fersch and Thomas Rummler of Karlsruhe
+Institute of Technology, Garmisch-Partenkirchen, Germany
+
+Alfonso Senatore, University of Calabria, Cosenza, Italy
+
+Brian Cosgrove, Ed Clark, Fernando Salas, Trey Flowers, Xia Feng,
+Yuqiong Liu, Nels Frazier,
+
+Fred Ogden, Dave Mattern, Don Johnson, and Tom Graziano of the National
+Oceanic and Atmospheric Administration Office of Water Prediction
+
+Ismail Yucel, Middle East Technical University, Ankara, Turkey
+
+Erick Fredj, The Jerusalem College of Technology, Jerusalem, Israel
+
+Amir Givati, Surface water and Hydrometeorology Department, Israeli
+Hydrological Service, Jerusalem.
+
+Antonio Parodi, Fondazione CIMA - Centro Internazionale in Monitoraggio
+Ambientale, Savona, Italy
+
+Blair Greimann, Sedimentation and Hydraulics section, U.S. Bureau of
+Reclamation
+
+Z George Xue and Dongxiao Yin, Louisiana State University
+
+Funding support for the development and application of the WRF-Hydro®
+modeling system has been provided by:
+
+The National Science Foundation and the National Center for Atmospheric
+Research
+
+The U.S. National Weather Service
+
+The Colorado Water Conservation Board
+
+Baron Advanced Meteorological Services
+
+National Aeronautics and Space Administration (NASA)
+
+National Oceanic and Atmospheric Administration (NOAA) Office of Water
+Prediction (OWP)
+
+
+.. toctree::
+    :hidden:
+
+    Preface / Acknowledgements <self>
+    introduction
+    model-code-config
+    model-physics
+    nudging
+    model-inputs-preproc
+    model-outputs
+    references
+    appendices