From 9ba0b36da88eab9db2a875f3a1bf31f1221f9321 Mon Sep 17 00:00:00 2001 From: Soren Rasmussen Date: Mon, 28 Aug 2023 12:06:39 -0600 Subject: [PATCH 1/3] Fixes two deprecation warning messages: - meets readthedocs' upcoming requirement for a version 2 .readthedocs.yaml file. - Use build.os instead of build.image in .readthedocs.yaml --- .readthedocs.yaml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..0b4e63bc --- /dev/null +++ b/.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 From 2fb06cba8a869d4daddd63163235a6ae3bd450b6 Mon Sep 17 00:00:00 2001 From: Soren Rasmussen Date: Mon, 28 Aug 2023 13:11:17 -0600 Subject: [PATCH 2/3] Enhancements: better organization of mkdocs.yml and removal of that deprecated method for doing google analytics. Small formatting changes if markdown files --- docs/developing.md | 16 ++++++++-------- docs/running/settings_documentation.md | 2 +- mkdocs.yml | 20 +++++++++++++------- 3 files changed, 22 insertions(+), 16 deletions(-) diff --git a/docs/developing.md b/docs/developing.md index 33400a3f..95b87506 100644 --- a/docs/developing.md +++ b/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. diff --git a/docs/running/settings_documentation.md b/docs/running/settings_documentation.md index 35986f48..78b51f74 100644 --- a/docs/running/settings_documentation.md +++ b/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__: diff --git a/mkdocs.yml b/mkdocs.yml index 67d1f094..a2852710 100644 --- a/mkdocs.yml +++ b/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'] From 3843a56814e8c645b0f25be78c5698366e4c097d Mon Sep 17 00:00:00 2001 From: Soren Rasmussen Date: Tue, 29 Aug 2023 15:32:24 -0600 Subject: [PATCH 3/3] Since markdown files and readthedocs settings on the main branch are being edited, changing the readthedocs link to the 'latest' for right now. The 'latest' url is built from the main branch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fd734d15..a1474c06 100644 --- a/README.md +++ b/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.