Modifying for readthedocs switch, changing BUILD file to restructured…

… format and adding Makefile
NCAR · Nov 6, 2024 · c7ddaaf · c7ddaaf
1 parent 880239a
commit c7ddaaf
Show file tree

Hide file tree

Showing 7 changed files with 128 additions and 73 deletions.
diff --git a/.gitignore b/.gitignore
@@ -5,6 +5,7 @@
 *.lst
 *~
 Makefile.comm
+docs/_build/
 src/lib/*
 src/macros
 src/HRLDAS/user_build_options

diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@ WRF-Hydro is a community modeling system and framework for hydrologic modeling a
 
 ## Documentation
 Documentation and in-depth build instructions can be found on our [project website](https://ral.ucar.edu/projects/wrf_hydro/technical-description-user-guide).
-Quick [build instructions](docs/BUILD.md) for CMake are also available.
+Quick [build instructions](docs/BUILD.rst) for CMake are also available.
 
 ## Resources and Support
 For news and updates regarding the WRF-Hydro project please subscribe to our [email list](https://ral.ucar.edu/projects/wrf_hydro/subscribe).

diff --git a/docs/BUILD.md b/docs/BUILD.md
diff --git a/docs/BUILD.rst b/docs/BUILD.rst
@@ -0,0 +1,101 @@
+Build
+===========
+
+
+Requirements
+~~~~~~~~~~~~
+
++------------+---------+
+|Compiler    | Version |
++============+=========+
+| GNU        | 7.4+    |
++------------+---------+
+| Intel      | 2018+   |
++------------+---------+
+| NVidia/PGI | 20.4+   |
++------------+---------+
+| Cray       | 8+      |
++------------+---------+
+
++--------------------+---------+
+| Libraries/Software | Version |
++====================+=========+
+| MPI                | 3.x+    |
++--------------------+---------+
+| Fortran NetCDF     | 4.4+    |
++--------------------+---------+
+| CMake              | 3.12+   |
++--------------------+---------+
+
+
+CMake Build
+~~~~~~~~~~~
+
+.. code-block:: bash
+
+    $ mkdir build
+    $ cd build
+    $ cmake ..
+    $ make -j 4
+
+The executables, namelists and tables are now in the ``build/Run`` directory.
+Testcases with domain setups can be found `here <https://ral.ucar.edu/projects/wrf_hydro/testcases>`_.
+To build with additional functionality, enter ``cmake .. -DFOO=1`` where the
+available options are described in the following table.
+
++------------------------------------+-------------------------------------------------------------------------------+
+| CMake WRF-Hydro Specific Options   | Functionality                                                                 |
++====================================+===============================================================================+
+| ``-DWRF_HYDRO=1``                  | Default: turn on WRF-Hydro                                                    |
++------------------------------------+-------------------------------------------------------------------------------+
+| ``-DHYDRO_D=1``                    | Enhanced diagnostic output for debugging                                      |
++------------------------------------+-------------------------------------------------------------------------------+
+| ``-DSPATIAL_SOIL=1``               | Spatially distributed parameters for NoahMP                                   |
++------------------------------------+-------------------------------------------------------------------------------+
+| ``-DWRF_HYDRO_NUDGING=1``          | Enable the streamflow nudging routines for Muskingum-Cunge Routing            |
++------------------------------------+-------------------------------------------------------------------------------+
+| ``-DNWM_META=1``                   | Output NWM Metadata                                                           |
++------------------------------------+-------------------------------------------------------------------------------+
+| ``-DOUTPUT_CHAN_CONN=1``           | For gridded channel routing, write the channel connectivity to a netcdf file  |
++------------------------------------+-------------------------------------------------------------------------------+
+| ``-DPRECIP_DOUBLE=1``              | Double precipitation from hydro forcing                                       |
++------------------------------------+-------------------------------------------------------------------------------+
+| ``-DNCEP_WCOSS=1``                 | Do not use unless working on the WCOSS machines                               |
++------------------------------------+-------------------------------------------------------------------------------+
+
++------------------------------------+-------------------------------------------------------------------------------+
+| Unsupported Functionality          |                                                                               |
++====================================+===============================================================================+
+| ``-DWRF_HYDRO_NUOPC=1``            | Coupling with NUOPC, this option is not currently supported                   |
++------------------------------------+-------------------------------------------------------------------------------+
+| ``-DWRF_HYDRO_RAPID=1``            | Coupling with the RAPID routing model, this option is not currently supported |
++------------------------------------+-------------------------------------------------------------------------------+
+
+
+CMake Testcase
+~~~~~~~~~~~~~~
+
+To download and setup the Croton testcase in ``build/Run`` use one of the
+following commands.
+The first time the ``croton.tar.gz`` file will be downloaded, extracted, and configured.
+Future commands will reconfigure the ``Run`` directory.
+
++---------------------------------+
+| Make Command                    |
++=================================+
+| make croton                     |
++---------------------------------+
+| makep croton-gridded            |
++---------------------------------+
+| make croton-gridded-no-lakes    |
++---------------------------------+
+| make croton-nwm                 |
++---------------------------------+
+| make croton-nwm_ana             |
++---------------------------------+
+| make croton-nwm_longe_range     |
++---------------------------------+
+| make croton-reach               |
++---------------------------------+
+| make croton-reach-lakes         |
++---------------------------------+
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+SOURCEDIR = userguide/
+BUILDDIR = _build/html
+
+# List all source files to track dependencies
+SOURCE_FILES = $(shell find . -name '*.rst' -o -name '*.rest' -o -name '*.py' -o -name '*.css')
+
+all: build
+
+build: $(BUILDDIR)/index.html
+
+$(BUILDDIR)/index.html: $(SOURCE_FILES)
+	@echo "Building readthedocs documentation"
+	sphinx-build -b html $(SOURCEDIR) $(BUILDDIR)
+	@echo "Open $(BUILDDIR)/index.html to preview readthedocs documentation"
+
+open: build
+	open $(BUILDDIR)/index.html
+
+clean:
+	rm -rf _build
diff --git a/docs/userguide/conf.py b/docs/userguide/conf.py
@@ -14,6 +14,7 @@
         'navigation_depth': -1
     }
 except:
+    print("Warning: sphinx_rtd_theme not installed, using default theme")
     pass
 html_static_path = ['_static']
 html_css_files = ['ug_theme.css']

diff --git a/docs/userguide/model-code-config.rest b/docs/userguide/model-code-config.rest
@@ -462,3 +462,7 @@ model, the WRF model input file namelist.input becomes the second
 namelist file. Full annotated example namelist.hrldas files for Noah and
 Noah-MP are provided in :ref:`section-a3` and :ref:`section-a4`.
 
+2.8 Build Instructions
+------------------------------------
+.. include:: ../BUILD.rst
+   :start-line: 2