Merge pull request #171 from scrasmussen/bugfix/upcoming-readthedocs-…

…deprecation-fixes

Bugfix/upcoming readthedocs deprecation fixes

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# on both this MkDocs setup and available Sphinx setup
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+ os: ubuntu-22.04
+ tools:
+ python: "3.11"
+
+mkdocs:
+ configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+# python:
+# install:
+# - requirements: docs/requirements.txt

README.md

@@ -8,7 +8,7 @@ ICAR is a simplified atmospheric model designed primarily for climate downscalin
 
 In ICAR 2.0 (currently early alpha), ICAR supports parallelization across hundreds of computing nodes (the basic physics have been shown to scale up to nearly 100,000 processors) using coarray fortran. This version of the code has a significant overhaul of the original code base, and as a result not all functionality has been restored yet.
 
-Documentation is (slowly) being built on [readthedocs](http://icar.readthedocs.org/en/develop/) and doxygen based documentation can be built now by running "make doc", and is available through [github-pages](http://NCAR.github.io/icar).
+Documentation is (slowly) being built on [readthedocs](http://icar.readthedocs.org/en/latest/) and doxygen based documentation can be built now by running "make doc", and is available through [github-pages](http://NCAR.github.io/icar).
 
 #### Requirements
 To run the model 3D time-varying atmospheric data are required, though an ideal test case can be generated for simple simulations as well. See "Running the Model" below. There are some sample python scripts to help make input forcing files, but the WRF pre-processing system can also be used. Low-resolution WRF output files can be used directly, various reanalysis and GCM output files can be used with minimal pre-processing (just get all the variables in the same netcdf file.) In addition, a high-resolution netCDF topography file is required. This will define the grid that ICAR will run on. Finally and ICAR options file is used to specify various parameters for the model. A sample options file is provided in the run/ directory.

docs/developing.md

@@ -9,14 +9,14 @@ For an outline of the basic code structure see the [ICAR code overview](icar_cod
 
 For a more complete documentation of ICAR, see the [detailed ICAR code description](http://ncar.github.io/icar/). This full description is being updated as the doxygen markup is added to the code. It also has detailed interactive diagrams of the inter-relationship between all functions. For the overview, start by looking at the [documentation for the main program](http://ncar.github.io/icar/driver_8f90.html).
 
-ICAR main is now a significant change to the internal workings of ICAR, and has made some components vastly more dynamic and easier to implement / modify. However, to support that, some elements became more complicated. For example, adding a new variable to the output file is incredibly easy if that variable already exists. Just add it to a call (almost anywhere) to output%add_variables()... however, if that variables has not been added before there are several steps that need to occur. Below is a quick outline of the process:
-
-1) The variable has to be a a “variable_t” type, not just an array (and preferably part of the domain object though not technically required, but other steps below would be different if it is not.)
-2) That variable needs to have an entry in the kVARS structure in the `constants/icar_constants.f90` file.
-3) That variable needs to have an entry in the default metadata array `io/default_output_metadata.f90`.
-4) That variable needs to be initialized somewhere appropriate (for example in `objects/domain_obj.f90` `create_variables`.)
-5) Somewhere you need to tell it to write that variable too. The easiest place to do this is in the domain_obj routine `var_request`, add it to the list of variables to be allocated, **and** to the list of “restart” variables (i.e. output variables for now).
-6) The one change that needs to be made in `io/output_obj.f90` is to add a single line for that variable to the `add_variables` routine.
+ICAR main is now a significant change to the internal workings of ICAR, and has made some components vastly more dynamic and easier to implement/modify. However, to support that, some elements became more complicated. For example, adding a new variable to the output file is incredibly easy if that variable already exists. Just add it to a call (almost anywhere) to `output%add_variables()` however, if that variables has not been added before there are several steps that need to occur. Below is a quick outline of the process:
+
+1. The variable has to be a a “variable_t” type, not just an array (and preferably part of the domain object though not technically required, but other steps below would be different if it is not.)
+2. That variable needs to have an entry in the kVARS structure in the `constants/icar_constants.f90` file.
+3. That variable needs to have an entry in the default metadata array `io/default_output_metadata.f90`.
+4. That variable needs to be initialized somewhere appropriate (for example in `objects/domain_obj.f90` `create_variables`.)
+5. Somewhere you need to tell it to write that variable too. The easiest place to do this is in the domain_obj routine `var_request`, add it to the list of variables to be allocated, **and** to the list of “restart” variables (i.e. output variables for now).
+6. The one change that needs to be made in `io/output_obj.f90` is to add a single line for that variable to the `add_variables` routine.
 
 I know that ended up being more complicated than it could be. Once a variable is in that format, it is really easy to add and remove variables (and for that matter create multiple output files with different variable lists in each, it is almost magical), but the initial setup is non-trivial to get there.
 

docs/running/settings_documentation.md

@@ -1,6 +1,6 @@
 ## ICAR settings file documentation
 
-Reading the comments in the run/short_icar_options.nml or run/complete_icar_options.nml files may be some of the best documentation available.
+Reading the comments in the [run/short_icar_options.nml](https://github.com/NCAR/icar/blob/main/run/short_icar_options.nml) or [run/complete_icar_options.nml](https://github.com/NCAR/icar/blob/main/run/complete_icar_options.nml) files may be some of the best documentation available.
 
 ### Main Namelists
 __REQUIRED__:

mkdocs.yml

@@ -1,10 +1,16 @@
 site_name: ICAR
 nav:
-- Home: index.md
-- Compiling: compiling.md
-- Running: running/running.md
-- Settings Documentation: running/settings_documentation.md
-- Developing: developing.md
-- Errors: errors.md
+ - Home: index.md
+ - ICAR Code Overview: icar_code_overview.md
+ - Compiling: compiling.md
+ - Running: running/running.md
+ - Settings Documentation: running/settings_documentation.md
+ - Developing: developing.md
+ - Errors: errors.md
+ - FAQ: FAQ.md
+ - How To:
+ - Build MkDocs: howto/build_mkdocs.md
+ - ICAR and Git: howto/icar_and_git_howto.md
+ - ICAR Git Workflow: howto/icar_git_workflow.md
 theme: readthedocs
-google_analytics: ['UA-108421993-4', 'icar.readthedocs.org']
+# google_analytics: ['UA-108421993-4', 'icar.readthedocs.org']