search

ESCOMP / CISM-wrapper

Community Ice Sheet Model wrapper for CESM
http://www.cesm.ucar.edu/models/cesm2.0/land-ice/
Other
3 stars 16 forks source link

Documentation for CESM2 release #12

Open billsacks opened 6 years ago

billsacks commented 6 years ago

This issue documents things needed for the cism-in-cesm documentation for the cesm2 release.

Other things we want to mention somewhere:

billsacks commented 6 years ago

@whlipscomb @gunterl I have added chapter assignments in the comment above. (Bill L: no need to deal with this right now - just within the next few weeks.)

whlipscomb commented 6 years ago

@billsacks, Thanks for putting together this outline. I'll work on this after the code is frozen and the draft paper is done. (It's going to be a busy month.)

billsacks commented 6 years ago

@gunterl and @whlipscomb - Okay, I have done the initial reorganization of the documentation that @gunterl and I came up with (sorry this has taken me a while to complete!). I have created a branch in this repo named doc_work where we can continue to work on this documentation. My plan is that we can then merge this branch to both master and the release branch. (I have done an initial merge of this branch to both master and release just now.)

The build of the documentation is here:

https://escomp.github.io/cism-docs/cism-in-cesm/doc_work/html/index.html

There are instructions on how to build the documentation on the doc_work branch, under doc/README.md (I'm not sure all of these instructions are correct and up-to-date, though: I copied some of them from an older wiki page). If you don't want to struggle with the documentation build, don't worry about it for now: I can do the build periodically. Note that you can view a sort-of-pretty version of the documentation in the github view of an rst page, e.g., https://github.com/ESCOMP/cism-wrapper/blob/doc_work/doc/source/ice-sheets-in-clm.rst

billsacks commented 6 years ago

@whlipscomb you had a lot of good information in the quick start section (at least, I think you're the one who wrote that) - generally describing how to use CESM. However, some of it is out of date. Rather than trying to update all of it, I'm just removing it for now, pointing people to existing documentation. (I'll push these changes up soon.)

I wanted to give you a heads-up about this in case you want to reinstate any of that.

whlipscomb commented 6 years ago

@billsacks, Thanks for the heads-up. I doubt I'll have time to update this section before the release. Maybe @gunterl and I can reinstate an updated version of the section at a later date.

billsacks commented 6 years ago

@gunterl - for now I am completely removing the section on "simulating the Greenland ice sheet". We had talked about moving it to the "quick start" section (now called "Running and modifying the CESM land ice component", but it feels very out of place there). I'm not sure this section is necessary, but if you want it, you can dig up the original version from an earlier commit.

billsacks commented 6 years ago

@whlipscomb and @gunterl I am making some progress on what I view as the most critical sections that were assigned to me - see checklist above. The main piece that's done now is the new section 2, "Running and modifying the CESM land ice component". I have also added an appendix on adding a new CISM grid, because this mostly consisted of moving information off of the wiki into this documentation. The one additional piece I want to do before leaving tomorrow morning is to fix the documentation of TG compsets. If I don't finish it then, it will be a high priority for me at the end of next week.

Again, see the doc_work branch in this repository, as well as https://escomp.github.io/cism-docs/cism-in-cesm/doc_work/html/ for the current build. Feel free to modify as you see fit.

gunterl commented 6 years ago

Hi @billsacks,

Thanks for working on this. I will be make progress on my part this week.

On Sun, Jun 3, 2018 at 10:54 AM, Bill Sacks notifications@github.com wrote:

@whlipscomb https://github.com/whlipscomb and @gunterl https://github.com/gunterl I am making some progress on what I view as the most critical sections that were assigned to me - see checklist above. The main piece that's done now is the new section 2, "Running and modifying the CESM land ice component". I have also added an appendix on adding a new CISM grid, because this mostly consisted of moving information off of the wiki into this documentation. The one additional piece I want to do before leaving tomorrow morning is to fix the documentation of TG compsets. If I don't finish it then, it will be a high priority for me at the end of next week.

Again, see the doc_work branch in this repository, as well as https://escomp.github.io/cism-docs/cism-in-cesm/doc_work/html/ for the current build. Feel free to modify as you see fit.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/ESCOMP/cism-wrapper/issues/12#issuecomment-394175497, or mute the thread https://github.com/notifications/unsubscribe-auth/AH0K-PnErm7T3bwxgOm5XJ5nJ0HTaLnKks5t5BTfgaJpZM4T1HtT .

billsacks commented 6 years ago

I am partially done the section on T/TG compsets (section 3): I have gone over subsections 1, 2 and 4 here. I just need to rewrite subsection 3 (creating and running with your own forcing data).

billsacks commented 6 years ago

@whlipscomb and @gunterl - I don't think I'll get any more chance to work on this before leaving on vacation through Thursday, so here's a summary of where things stand: I've been working on the doc_work branch in this repository. The latest build is here: https://escomp.github.io/cism-docs/cism-in-cesm/doc_work/html/ . I am finished drafts of the following sections:

I'd be happy to get your reviews or edits of those sections.

When I return, my highest priority will be rewriting section 3.3. Beyond that, I need to do a lot of work on section 5 (Ice sheets in the Community Land Model, and glacier-land coupling) to bring it up to date with the latest capabilities. That probably won't be done in time for the release (unless the release is delayed) so my plan is to temporarily remove that page (and any other incorrect pages) from the index until they're corrected, so people won't stumble across grossly incorrect information.

gunterl commented 6 years ago

@billsacks, thank you so much for the great progress.

On Mon, Jun 4, 2018 at 8:41 AM, Bill Sacks notifications@github.com wrote:

@whlipscomb https://github.com/whlipscomb and @gunterl https://github.com/gunterl - I don't think I'll get any more chance to work on this before leaving on vacation through Thursday, so here's a summary of where things stand: I've been working on the doc_work branch in this repository. The latest build is here: https://escomp.github.io/cism- docs/cism-in-cesm/doc_work/html/ . I am finished drafts of the following sections:

-

  1. Running and modifying the CESM land ice component

  2. Running the standalone ice sheet model within CESM: T compsets

    Finished drafts of 3.1, 3.2, 3.4

    Still need to rewrite 3.3

  3. Controlling output from CISM and CLM

I'd be happy to get your reviews or edits of those sections.

When I return, my highest priority will be rewriting section 3.3. Beyond that, I need to do a lot of work on section 5 (Ice sheets in the Community Land Model, and glacier-land coupling) to bring it up to date with the latest capabilities. That probably won't be done in time for the release (unless the release is delayed) so my plan is to temporarily remove that page (and any other incorrect pages) from the index until they're corrected, so people won't stumble across grossly incorrect information.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/ESCOMP/cism-wrapper/issues/12#issuecomment-394379146, or mute the thread https://github.com/notifications/unsubscribe-auth/AH0K-K-eh4-gw47Yvf44UPa0WbSZTMzRks5t5UcbgaJpZM4T1HtT .

billsacks commented 6 years ago

@whlipscomb here are the sections I envision writing (roughly) for chapter 5:

In addition, at least some of the existing sections in ice-sheets-in-clm.rst should probably be kept, though maybe in abbreviated form.

Maybe we really need two sections:

  1. "Ice sheets in CLM" - will include some of the existing information from ice-sheets-in-clm.rst that is CLM-centric, plus the above section on CLM's possible glacier behaviors

  2. CISM-CLM coupling

I'm open to any thoughts you have on the best way to organize this material.

billsacks commented 5 years ago

I have (finally) merged the doc_work branch to both master and the release branch. I haven't done any work on it lately, but I couldn't remember why I hadn't merged it long ago, so decided it was probably time to merge it, partly to facilitate some other documentation changes needed soon.

billsacks commented 5 years ago

Alice Bertini showed me the nice marbl docs: https://marbl-ecosys.github.io/versions/latest/ , with particular reference to how they do the pull-down for the versions. I took a quick stab at trying to get that working here:

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 6f1740d..8c85cc6 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -88,13 +88,16 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'bizstyle'
+import sphinx_rtd_theme
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {}
+html_theme_options['versions'] = {'latest': '../master', 'cesm2.0': '../release-cesm2.0'}

 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

But that is apparently not enough (the build generates WARNING: unsupported theme option 'versions' given, and doesn't result in the version pull-down). Digging a bit more, it looks like we might need the js file from https://github.com/marbl-ecosys/MARBL/commit/ddd346f138b62c8415a0671f59777897ca956c99 . Since I don't understand that, I'm not prepared to bring it in yet. Also, I don't like that (apparently) every branch needs to have a hard-coded list of versions... does that imply that, if you add a version, all branches need to change? I'm going to wait for Alice to look at this and possibly come up with an improvement.

billsacks commented 5 years ago

@whlipscomb @gunterl - I am done the pieces that I was assigned. See the checklist at the top of this issue for the remaining needs.

A few notes about my recent changes: