From 01df5cb0ad71d14c6f5eb2c5c75325074f19b82c Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 6 Aug 2020 16:37:20 -0600 Subject: [PATCH 1/4] Bring in documentation changes from master It looks like documentation was updated on master at some point but not on this branch. --- doc/README | 2 +- doc/source/cesm_configurations.rst | 22 +++++++++++----------- doc/source/downloading_cesm.rst | 8 ++++---- doc/source/introduction.rst | 4 ++-- doc/source/quickstart.rst | 15 +++++++-------- 5 files changed, 25 insertions(+), 26 deletions(-) diff --git a/doc/README b/doc/README index 6ab73407a4..897c80c905 100644 --- a/doc/README +++ b/doc/README @@ -5,7 +5,7 @@ cesm/doc directory: >make html The build/html files should be copied to the appropriate release or -development https://github.com/ESCOMP/cesm gh-pages orphan branch +development https://github.com/ESCOMP/CESM gh-pages orphan branch subdirectory and commited to that branch separately. Only the doc/source files are stored with the code on the master diff --git a/doc/source/cesm_configurations.rst b/doc/source/cesm_configurations.rst index e2585d123e..8e174c1b0f 100644 --- a/doc/source/cesm_configurations.rst +++ b/doc/source/cesm_configurations.rst @@ -12,9 +12,9 @@ a science and technical perspective. CESM supports numerous `_. In addition, each model component has input options to configure specific `model settings -`_ +`_ and `parameterizations -`_. +`_. CESM2 Components @@ -35,7 +35,7 @@ and an external system processing component - external system processing (esp) In addition CESM2 is accompanied by a `driver/coupler (cpl7) -`_ that coordinates +`_ that coordinates the time evolution of geophysical components and periodically permits the components to exchange data. Each component is represented in one of several modes: "active," "data," "dead," or "stub" that permits the @@ -73,24 +73,24 @@ The CESM2 components can be summarized as follows: :widths: 12, 10, 10, 10, 60 "atmosphere","atm","cam", "active","The `Community Atmosphere Model (CAM) `_ is a global atmospheric general circulation model developed from the NCAR CCM3." - "atmosphere","atm","datm", "data", "The `data atmosphere `_ component is a pure data component that reads in atmospheric forcing data" + "atmosphere","atm","datm", "data", "The `data atmosphere `_ component is a pure data component that reads in atmospheric forcing data" "atmosphere","atm", "xatm", "dead", "Used only for testing the driver/coupler" "atmosphere","atm", "satm", "stub", "Used only to satisy the interface requirements" "land", "lnd", "clm", "active", "The `Community Land Model (CLM) `_ is the result of a collaborative project between scientists in the Terrestrial Sciences Section of the Climate and Global Dynamics Division (CGD) at NCAR and the CESM Land Model Working Group. Other principal working groups that also contribute to the CLM are Biogeochemistry, Paleoclimate, and Climate Change and Assessment." - "land", "lnd", "dlnd", "data", "The `data land component `_ is a purely data-land component (reading in coupler history data for atm/land fluxes and land albedos produced by a previous run, or snow surface mass balance fields) or both." + "land", "lnd", "dlnd", "data", "The `data land component `_ is a purely data-land component (reading in coupler history data for atm/land fluxes and land albedos produced by a previous run, or snow surface mass balance fields) or both." "land", "lnd", "xlnd", "dead", "Used only for testing the driver/coupler" "land", "lnd", "slnd", "stub", "Used only to satisy the interface requirements" "river", "rof", "rtm", "active", "The `river transport model (RTM) `_ was previously part of CLM and was developed to route total runoff from the land surface model to either the active ocean or marginal seas which enables the hydrologic cycle to be closed (Branstetter 2001, Branstetter and Famiglietti 1999). This is needed to model ocean convection and circulation, which is affected by freshwater input." "river", "rof", "mosart", "active", "`MOdel for Scale Adaptive River Transport (MOSART) `_ , a new large-scale river routing model. MOSART improves the magnitude and timing of river flow simulations." - "river", "rof", "drof", "data", "The `data runoff model `_ was previously part of the data land model and functions as a purely data-runoff model (reading in runoff data)." + "river", "rof", "drof", "data", "The `data runoff model `_ was previously part of the data land model and functions as a purely data-runoff model (reading in runoff data)." "river", "rof", "xrof", "dead", "Used only for testing the driver/coupler" "river", "rof", "srof", "stub", "Used only to satisy the interface requirements" "ocean", "ocn", "pop", "active", "The ocean model is an extension of the `Parallel Ocean Program (POP) `_ Version 2 from Los Alamos National Laboratory (LANL)." - "ocean", "ocn", "docn", "data", "The `data ocean `_ component has two distinct modes of operation. It can run as a pure data model, reading ocean SSTs (normally climatological) from input datasets, interpolating in space and time, and then passing these to the coupler. Alternatively, docn can compute updated SSTs based on a slab ocean model where bottom ocean heat flux convergence and boundary layer depths are read in and used with the atmosphere/ocean and ice/ocean fluxes obtained from the coupler." + "ocean", "ocn", "docn", "data", "The `data ocean `_ component has two distinct modes of operation. It can run as a pure data model, reading ocean SSTs (normally climatological) from input datasets, interpolating in space and time, and then passing these to the coupler. Alternatively, docn can compute updated SSTs based on a slab ocean model where bottom ocean heat flux convergence and boundary layer depths are read in and used with the atmosphere/ocean and ice/ocean fluxes obtained from the coupler." "ocean", "ocn", "xocn", "dead" "ocean", "ocn", "socn", "stub" "sea-ice", "ice", "cice", "active", "The `sea-ice component (CICE) `_ is an extension of the Los Alamos National Laboratory (LANL) sea-ice model and was developed though collaboration within the CESM Polar Climate Working Group (PCWG). In CESM, CICE can run as a fully prognostic component or in prescribed mode where ice coverage (normally climatological) is read in." - "sea-ice", "ice", "dice", "data", "The `data ice `_ component is a partially prognostic model. The model reads in ice coverage and receives atmospheric forcing from the coupler, and then it calculates the ice/atmosphere and ice/ocean fluxes. The data ice component acts very similarly to CICE running in prescribed mode." + "sea-ice", "ice", "dice", "data", "The `data ice `_ component is a partially prognostic model. The model reads in ice coverage and receives atmospheric forcing from the coupler, and then it calculates the ice/atmosphere and ice/ocean fluxes. The data ice component acts very similarly to CICE running in prescribed mode." "sea-ice", "ice", "xice", "dead", "Used only for testing the driver/coupler" "sea-ice", "ice", "sice", "stub" "land-ice", "glc", "cism", "active", The `CISM component `_ is an extension of the Glimmer ice sheet model. @@ -98,7 +98,7 @@ The CESM2 components can be summarized as follows: "ocean-wave", "wav", "wav", "ww3","The `ww3 `_ component adds prognostic ocean waves to the system" "ocean-wave", "wav", "xwav", "dead", "Used only for testing the driver/coupler" "ocean-wave", "wav", "swav", "stub", "Used only to satisy the interface requirements" - "coupler", "cpl", "cpl", "active", "The `CESM coupler `_ was built primarily through a collaboration of the NCAR CESM Software Engineering Group and the Argonne National Laboratory (ANL). The MCT coupling library provides much of the infrastructure." + "coupler", "cpl", "cpl", "active", "The `CESM coupler `_ was built primarily through a collaboration of the NCAR CESM Software Engineering Group and the Argonne National Laboratory (ANL). The MCT coupling library provides much of the infrastructure." CESM2 Component Sets @@ -181,7 +181,7 @@ files to fill in information required for the target platform. This functionality is handy in accelerating the porting process and quickly getting a case running on a new platform. For more information on porting, see the `CIME porting guide -`_. The +`_. The list of available machines are documented in `CESM supported machines `_. Running **query_config** with the ``--machines`` option will also show @@ -204,7 +204,7 @@ These control runs should be scientifically reproducible on the original platform or other platforms. Bit-for-bit reproducibility cannot be guaranteed due to variations in compiler or system versions. Users should carry out their own `port validations -`_ +`_ on any platform prior to doing scientific runs or scientific analysis and documentation. diff --git a/doc/source/downloading_cesm.rst b/doc/source/downloading_cesm.rst index cf5b60841b..6b8652f33d 100644 --- a/doc/source/downloading_cesm.rst +++ b/doc/source/downloading_cesm.rst @@ -8,7 +8,7 @@ Downloading the code and scripts -------------------------------- Starting with CESM2, releases are available through a public GitHub -repository, `http://github.com/ESCOMP/cesm `_. +repository, `http://github.com/ESCOMP/CESM `_. Access to the code requires both git and Subversion client software in place that is compatible with GitHub and our Subversion server @@ -16,7 +16,7 @@ software. You will need access to the command line clients, ``git`` (v1.8 or greater) and ``svn`` (v1.8 or greater but less than v1.11). Currently, our Subversion server software is at version 1.8.17. For more information or to download -open source tools, visit `Subversion `_ +open source tools, visit `Subversion `_ and `git downloads `_. With valid git and svn clients installed on the machine where CESM will be @@ -25,7 +25,7 @@ code: .. code-block:: console - git clone -b release-cesm2.1.0 https://github.com/ESCOMP/cesm.git my_cesm_sandbox + git clone -b release-cesm2.1.1 https://github.com/ESCOMP/CESM.git my_cesm_sandbox cd my_cesm_sandbox To checkout a previous version of CESM, first view the available versions: @@ -51,7 +51,7 @@ The **checkout_externals** script will read the configuration file called ``Exte will download all the external component models and CIME into /path/to/my_cesm_sandbox. Details regarding the CESM checkout process are available in the CESM GitHub repo -`README `_ +`README `_ To see more details regarding the checkout_externals script from the command line, type: .. code-block:: console diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst index b79b5429f8..7d2a591756 100644 --- a/doc/source/introduction.rst +++ b/doc/source/introduction.rst @@ -66,7 +66,7 @@ into the Earth's past, present, and future climate states. CESM can be run on a number of different `hardware platforms `__, and has a relatively flexible design with respect to `processor layout -`__ +`__ of components. The CESM project is a cooperative effort among U.S. climate @@ -113,7 +113,7 @@ installing and running CESM2. - `pnetcdf 1.7.0 is required and 1.8.1 is optional but recommended `_ -- `Trilinos `_ may be required for certain configurations +- `Trilinos `_ may be required for certain configurations - `LAPACK `_ and `BLAS `_ diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index 638f4a3d96..e8b424ff43 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/quickstart.rst @@ -7,7 +7,7 @@ The following quick start guide is for versions of CESM2 that have already been ported to the local target machine. CESM2 is built on the CIME (Common Infrastructure for Modeling Earth) framework. -Please refer to the `CIME Porting Documentation `_ if CIME has not +Please refer to the `CIME Porting Documentation `_ if CIME has not yet been ported to the target machine. If you are new to CESM2, please consider reading the @@ -15,7 +15,7 @@ If you are new to CESM2, please consider reading the This is the procedure for quickly setting up and running a CESM2 case. -Download CESM2 (see `Downloading CESM2 `_). +Download CESM2 (see `Downloading CESM2 `_). Select a component set, and a resolution for your case. Details of available component sets and resolutions are available from the `query_config`_ tool located @@ -152,7 +152,7 @@ now are: ./xmlquery STOP_OPTION,STOP_N These default settings can be useful in `troubleshooting - `_ runtime problems + `_ runtime problems before submitting for a longer time, but will not allow the model to run long enough to produce monthly history climatology files. In order to produce history files, increase the run length to a month or longer: @@ -225,8 +225,7 @@ comma separated names and no spaces): .. _CIME: http://esmci.github.io/cime -.. _porting: http://esmci.github.io/cime/users_guide/porting-cime -.. _query_config: http://esmci.github.io/cime/users_guide/introduction-and-overview.html#discovering-available-cases-with-query-config -.. _create_newcase: http://esmci.github.io/cime/users_guide/create-a-case.html -.. _xmlchange: http://esmci.github.io/cime/Tools_user/xmlchange.html -.. _case.setup: http://esmci.github.io/cime/users_guide/setting-up-a-case.html +.. _query_config: http://esmci.github.io/cime/versions/master/html/users_guide/introduction-and-overview.html#discovering-available-cases-with-query-config +.. _create_newcase: http://esmci.github.io/cime/versions/master/html/users_guide/create-a-case.html +.. _xmlchange: http://esmci.github.io/cime/versions/master/html/Tools_user/xmlchange.html +.. _case.setup: http://esmci.github.io/cime/versions/master/html/users_guide/setting-up-a-case.html From c79da0dbc6c2dc9ec2c19104c26da842b0666c43 Mon Sep 17 00:00:00 2001 From: Bill Sacks Date: Thu, 6 Aug 2020 16:33:45 -0600 Subject: [PATCH 2/4] Switch to versioned documentation using sphinx rtd theme Follows instructions here https://drive.google.com/drive/u/0/folders/1WWlz6O1uBPUx7WdgQ24REFnuBrgpCM5U and here https://github.com/ESMCI/cime/pull/3439 --- doc/README | 39 ++++++++++++++++++++++++------- doc/source/_static/pop_ver.js | 37 +++++++++++++++++++++++++++++ doc/source/_templates/footer.html | 5 ++++ doc/source/_templates/layout.html | 3 +++ doc/source/conf.py | 22 ++++++++++++----- 5 files changed, 92 insertions(+), 14 deletions(-) create mode 100644 doc/source/_static/pop_ver.js create mode 100644 doc/source/_templates/footer.html create mode 100644 doc/source/_templates/layout.html diff --git a/doc/README b/doc/README index 897c80c905..b665520211 100644 --- a/doc/README +++ b/doc/README @@ -1,12 +1,35 @@ + +This requires Sphinx v1.7 or greater, as well as some add-ons, which can +be installed with: + +pip install sphinx +pip install sphinxcontrib-programoutput +pip install git+https://github.com/esmci/sphinx_rtd_theme.git@version-dropdown-with-fixes + +Check the sphinx version as follows: + +>sphinx-build --version + +The documentation source is stored with the CESM master code base. However, +the built html files are stored separately in the orphan gh-pages branch +and can be viewed from a browser at URL: + +http://escomp.github.io/cesm + +Details for working with the documentation are contained in the following +wiki page: + +https://github.com/ESMCI/cime/wiki/Working-with-Sphinx-and-reStructuredText + +(The procedure is the same for the CESM documentation as for the CIME +documentation.) + Use the following commands to auto-build the html documentation from the main cesm/doc directory: ->make clean ->make html - -The build/html files should be copied to the appropriate release or -development https://github.com/ESCOMP/CESM gh-pages orphan branch -subdirectory and commited to that branch separately. +make clean +make html -Only the doc/source files are stored with the code on the master -branch. \ No newline at end of file +To publish the docs to the orphan gh-pages branch, follow the steps in +https://github.com/ESMCI/cime/wiki/Working-with-Sphinx-and-reStructuredText +to ensure proper versioning of the documentation. diff --git a/doc/source/_static/pop_ver.js b/doc/source/_static/pop_ver.js new file mode 100644 index 0000000000..b8c58658a8 --- /dev/null +++ b/doc/source/_static/pop_ver.js @@ -0,0 +1,37 @@ +$(document).ready(function() { + /* For a URL that looks like + https://blah.github.io/versions/VERSIONFOO/html/bar/index.html, set cur_version_dir to + 'VERSIONFOO' (i.e., the portion of the path following 'versions'). + */ + var proj_end = document.baseURI.indexOf("versions") + 9; + var end = document.baseURI.indexOf("/", proj_end); + var cur_version_dir = document.baseURI.substring(proj_end, end); + var mylist = $("#version-list"); + mylist.empty(); + $.getJSON(version_json_loc, function(data) { + if (data.hasOwnProperty(cur_version_dir)) { + /* First add the current version so that it appears first in the drop-down + menu and starts as the selected element of the menu. If you click on the + current version, you should stay at the current page. + + The conditional around this block should generally be true, but we check it + just in case the current version is missing from the versions.json file for + some reason. + */ + cur_version_name = data[cur_version_dir]; + mylist.append($("