Update CDEPS documentation

[uturuncoglu]

Description of changes

This PR aims to update CDEPS documentation by adding missing pieces.

Specific notes

Contributors other than yourself, if any: @jedwards4b

CDEPS Issues Fixed (include github issue #): None

Are there dependencies on other component PRs (if so list): No

Are changes expected to change answers (bfb, different to roundoff, more substantial):
No. It changes only the documentation.

Any User Interface Changes (namelist or namelist defaults changes):
No

Testing performed (e.g. aux_cdeps, CESM prealpha, etc):
Not required

Hashes used for testing:
N/A

[uturuncoglu]

@jedwards4b @mvertens I am also plaining to add a section about extending data components by adding new data mode and creating mesh file (I know there is no single and robust way to do it but at least we could list the available tools and approaches). Please let me know if you want to cover any other topic.

[uturuncoglu]

@jedwards4b @mvertens I added new section about extending CDEPS by adding new data mode. It also has some information about creating ESMF mesh file for new data streams. I will create another PR to update gh-pages. @billsacks I realized that CMEPS and CDEPS do not use versioning in the documentation. Do we want to to have it? If so, what do we need to do for it in the configuration of the gh-pages.

[jedwards4b]

@uturuncoglu thank you for doing this - I think that you can look at the cime repo for examples of how to add versioning for documentation. That's a great idea.

[billsacks]

realized that CMEPS and CDEPS do not use versioning in the documentation. Do we want to to have it? If so, what do we need to do for it in the configuration of the gh-pages.

Whether you want versioning depends on the importance of maintaining old documentation versions for fixed releases. My guess is that this will be wanted at some point, but I'm not sure whether or not it's important now. You all probably have a better sense of this than I do.

If you do want it, you don't need to do anything on the GitHub side (GitHub doesn't do anything to support versioned documentation itself), but there are some important things in terms of the organization of the documentation branch / repo. Some of the necessary information is here (though some might be a bit out of date): https://docs.google.com/document/d/1ZoWzGwnLB5R_9DsJX3RVZhTBVfdlX5gY/edit . You can also look at the organization here:

https://github.com/ESCOMP/ctsm-docs

I'd also be happy to talk to you about it. It's not all fresh in my mind, but I can dig back up whatever is needed.

[mvertens]

@uturuncoglu - thank you so much for doing this. This is great.

[uturuncoglu]

I think we are creating tags for CDEPS to use under CESM (the last one is cdeps0.12.69) and it would be nice to have versioning in the documentation. I am not sure about having different version for each tag but at least we could start. BTW, why versioning in CDEPS side starts from 0.12.69. CDEPS seems pretty stable at this point. Are we plaining to tag a version like 1.0 etc.

[mvertens]

@uturuncoglu - I think your suggestion makes sense in terms of starting a tag series at 1.0. This might be a good tag to start it at since you have just updated the documentation. @jedwards4b and @billsacks - what are your thoughts?

[jedwards4b]

I would like to wait until I complete PR #203 which will remove shr_mpi_mod.

[uturuncoglu]

@jedwards4b Sure. Once you merge the PR #203, we could merge this once and create new tag. Then we could update gh-pages and use versioning started from 1.0.

[billsacks]

Updating the version to 1.x makes sense to me once you all feel it's ready.

As for the version: I would suggest maintaining a minimal number of different documentation versions. It's a pain to maintain multiple versions because when you notice a problem, you may need to fix it in many places. What we've been doing elsewhere is to just maintain a version of the documentation for major supported releases of host models – for example, we maintain versions of the CIME documentation for supported CESM and UFS releases. In practice, I think it will work best if you have a CDEPS release branch for each version of the documentation you are supporting... in general you'll probably want a CDEPS release branch for any major model release anyway (in case there are critical bug fixes needed on that release branch), so this should work out reasonably well.

[uturuncoglu]

@jedwards4b Can we now merge this one? BTW, do you want to create a 1.0 tag after this PR in?

[jedwards4b]

@uturuncoglu Yes, go ahead.