diff --git a/README.md b/README.md index d5aeff614..e5444dc27 100644 --- a/README.md +++ b/README.md @@ -7,33 +7,36 @@ CICE consists of a top level driver and dynamical core plus the Icepack column p ## Obtaining CICE +A list of the official CICE releases along with release notes is located here: +https://github.com/CICE-Consortium/CICE/releases + If you expect to make any changes to the code, we recommend that you first fork both the CICE and Icepack repositories. Basic instructions for working with CICE and Icepack are found in the [Git Workflow Guidance](https://github.com/CICE-Consortium/About-Us/wiki/Git-Workflow-Guidance), linked from the wikis in the primary code repositories https://github.com/CICE-Consortium/CICE/wiki https://github.com/CICE-Consortium/Icepack/wiki CICE may be obtained in several different ways: [not yet tested] 1. clone the full repository -See [Git Workflow Guidance](https://github.com/CICE-Consortium/About-Us/wiki/Git-Workflow-Guidance) +See [Git Workflow Guidance](https://github.com/CICE-Consortium/About-Us/wiki/Git-Workflow-Guidance) 2. check out only a particular branch, version or tag In the workflow for step 1 above, substitute - git clone -b branch_name --single-branch --recursive https://github.com/CICE-Consortium/CICE.git local_directory_name + git clone -b branch_name https://github.com/CICE-Consortium/CICE.git local_directory_name or use svn - svn co https://github.com/CICE-Consortium/CICE/branch_name + svn co https://github.com/CICE-Consortium/CICE/branch_name where "branch name" can also be a version name -3. download a tarball for a particular version -[how] - -## More information +3. download a tarball for a particular version from the git releases (see above) -Detailed and searchable online documentation of CICE can be found at https://cice-consortium.github.io/CICE/. In this documentation, a [“Quick Start”](https://cice-consortium.github.io/CICE/cice_1_introduction.html#quick-start-guide) subsection is available with instructions for running the model. A [“Testing”](https://cice-consortium.github.io/CICE/cice_3_user_guide.html#testing-cice) subsection with instructions for setting up standard tests (e.g. regression, restart) is also available. +## More Information -In-progress documentation (not yet merged into the main repo): https://duvivier.github.io/CICE/ - -The [wiki](https://github.com/CICE-Consortium/CICE/wiki) pages for each repository contain links to additional information, e.g. -- complete documentation +The [CICE wiki](https://github.com/CICE-Consortium/CICE/wiki) page contains links to additional information, e.g. +- complete documentation - both searchable html and pdf - larger files such as the gx1 grid, land mask, and forcing files - testing data -Test results for both CICE and Icepack can be found in the ["Test-Results" repository](https://github.com/CICE-Consortium/Test-Results). +The [Test-Results wiki](https://github.com/CICE-Consortium/Test-Results/wiki) has test results for both CICE and Icepack. + +The [About-Us repository](https://github.com/CICE-Consortium/About-Us) includes background and supporting information about the CICE Consortium, including how to interact with it. + +See also our [FAQ](https://github.com/CICE-Consortium/About-Us/wiki/FAQ). + + -The ["About-Us" repository](https://github.com/CICE-Consortium/About-Us) includes background and supporting information about the CICE Consortium, including how to interact with it. diff --git a/cicecore/version.txt b/cicecore/version.txt index 84a340b61..4e7d67669 100644 --- a/cicecore/version.txt +++ b/cicecore/version.txt @@ -1 +1 @@ -CICE 6.0.0.alpha +CICE v6.0.0.alpha diff --git a/doc/CICE-Consortium.pdf b/doc/CICE-Consortium.pdf deleted file mode 100644 index 1a80a3b23..000000000 Binary files a/doc/CICE-Consortium.pdf and /dev/null differ diff --git a/doc/about-sphinx-documentation.txt b/doc/about-sphinx-documentation.txt deleted file mode 100644 index 8e3bf471f..000000000 --- a/doc/about-sphinx-documentation.txt +++ /dev/null @@ -1,85 +0,0 @@ -Basic information about creating documentation with Sphinx -Alice DuVivier -July 14, 2017 ----------------------------------------------------------- - -INSTALLING SPHINX -You first need to install sphinx on your local machine. See here for more info on how to do this: -https://github.com/NCAR/CICE/wiki/Working-with-CICE-documentation-on-github-and-sphinx -I just had the NCAR ISG folks do it. Note that you will need the sphinxcontrib.bibtex library. - -CONVERTING LATEX TO RST CODE -If you start from a LaTeX (*.tex) document you will need to convert this to the restructured -text (*.rst) format that sphinx requires. A handy tool to do this is pandoc, which you can -install quickly and run from the command line. See here: http://pandoc.org/getting-started.html -The basic syntax is that at the command line you enter: -> panda NAMEIN.tex -f latex -t rst -s -ou NAMEOUT.rst -From here you can just start editing the NAMEOUT.rst files directly for sphinx. Note that this -did a beautiful job of converting the text, equations, and many tables. However, equation -numbering, section linking, references, figures, and some tables required more hands on care -to be sure they render correctly. -- Note: pandoc requires that the .tex files be in utf-8 encoding. To easily do this open the *.tex -document in Emacs then do ctrl-x ctrl-m f and you will be prompted to enter encoding type. Just -type in utf-8 and hit enter. Then save with ctrl-x ctrl-s . You are done and the document can be -converted with panda. - -CREATING AN ORPHAN BRANCH -To create documentation for a repository on GitHub we want to create an orphan branch for that -repository. An orphan branch is a branch that has no history in common with the master repo off -of which it was forked. In this case, the purpose for this is that the html pages created by -sphinx will exist in the orphan branch while the source *.rst code used to create the html exists -in the master repository. This way changes to the source code go into the evolving repository, but -changes to the html are isolated to the orphan branch and when you try to merge it avoids conflicts -related to the html that aren’t always caught by GitHub and could cause the documentation to break. - -To create an orphan branch, you will need owner status for a repository. Steps to create orphan branch: -On GitHub website create personal fork of the repo you’re interested in -On GitHub website from your fork, get link for the repository -On local machine: -> git clone URL -> git branch --l -> git checkout --orphan gh-pages -(creates the orphan branch gh-pages from master. Should have all documents in master to start) -> git rm -rf . -(removes everything in this repository. i.e. we are making it so their histories diverge) -> git status . -(check if all the files are gone) -> git echo “Documentation link goes here” > README.md -(it’s still nice to have a readme file) -> git add README.md -(this is all that will be in the branch) -> git commit -m “Initial commit to create gh-pages branch of repo” -> git remote --v -(get list of remote repositories and links. Should show your personal fork as “origin”) -> git push origin gh-pages -(adds the orphan branch to your local fork but not the original repo from which you forked) -> git remote add upstream URL -(add the URL for the original repository as your “upstream” repository. Get this from Github website) -> git remote --v -(verify that you now have an upstream remote URL too) -> git branch --l -(verify you are on the gh-pages branch only so that these changes will be pushed) -**** BE CAREFUL **** -> git push upstream gh-pages -(this pushes the gh-pages branch to the upstream repo. You may also want to try doing a pull request instead so that -others have a chance to look at what you’ve done. I did it both ways, I’d prefer the pull request method for the future). - -Now you have set up the orphan branch, but you need to build the sphinx stuff for it: -> git checkout master -(switch to master branch in order to set up doc/source directory it will use and other sphinx stuff) -> cd doc -> mkdir source -> sphinx-quickstart -(Your local machine will prompt you with interactive options to choose. I had Alice B.’s guidance to do this but could look at an old conf.py file to see what options were chosen. You only do this once for a repo but conf.py can be changed later on). -make/copy .gitignore from CICE repo to the main Icepack repository. Want to ignore html code when pushing to master branch. Also want to ignore emacs backup files (*~). -> git status -(should show the files conf.py, .gitignore, others? to initialize the sphinx stuff) -> git add . -> git commit -m “Initial setup for sphinx documentation” -> git push origin master -(push pages to your local master. Then either push upstream if you are an owner or *preferably* do a pull request to merge with the original repository) - -Make local gh-pages version for just the html. This is convenient so that you can have the master repo where you make code and another repo for the gh-pages branch from which you push the html. -> git clone -b gh-pages — single-branch https://github.com/duvivier/Icepack.git Icepack.gh-pages -(makes local copy of just gh-pages branch) - diff --git a/doc/cicedoc.pdf b/doc/cicedoc.pdf deleted file mode 100644 index 682f5f380..000000000 Binary files a/doc/cicedoc.pdf and /dev/null differ diff --git a/doc/source/conf.py b/doc/source/conf.py index 674b348f7..9d277bed4 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -62,7 +62,7 @@ # built documents. # # The short X.Y version. -version = u'6.0.0' +version = u'6.0.0.alpha' # The full version, including alpha/beta/rc tags. release = u'6.0.0.alpha' diff --git a/doc/sphinx-documentation-workflow.txt b/doc/sphinx-documentation-workflow.txt deleted file mode 100644 index ffaa4be75..000000000 --- a/doc/sphinx-documentation-workflow.txt +++ /dev/null @@ -1,72 +0,0 @@ -Basic workflow for github/sphinx documentation -Alice DuVivier -July 14, 2017 ----------------------------------------------------------- - -Most of this is adapted from https://github.com/ESMCI/cime/wiki/CIME-Git-Workflow, which has Figure 1 that is **VERY** useful -- Assumes you have sphinx installed on your own, personal machine. This includes the sphinxcontrib.bibtex library. Need to do this first. See the about-sphinx-documentation.txt file for more details. - -1. Editing *.rst files, testing html code, etc. in master branch -* Things to do once: -- Remotely: Create fork on personal GitHub area. Just do this once (usually). Use button on website of original repo to create this personal fork. -- Locally: Switch to your local machine -> cd ~/Documents/Research/github/CICE-Consortium/ —> go to local directory where you want to keep GitHub code, make changes, etc. -> git clone https://github.com/duvivier/CICE.git —> Clone the fork to your local machine from GitHub. Get the URL from which to clone from personal GitHub repository page, green “clone or download” button. -- This has now created a “local” copy of your fork called CICE. From here on you do changes from “local” fork on your local machine and push to your remote repo called “origin”. You can pull from “origin” or the original “upstream” remote repo. Any changes you want to eventually merge need to be pushed to the “origin” before issuing a pull request to “upstream” -> git status —> check that you’re on the master branch and have checked this out. -> git remote —v —> check your remote branches. Default will have just “origin” and it will push to your local fork. -> git remote add upstream https://github.com/CICE-Consortium/CICE —> add the consortium as the ultimate upstream source. Will need this for daily updates (see below). -> git remote —v —> check that the “upstream” branch has been added - -* Things you do daily: -> cd ~/Documents/Research/github/CICE-Consortium/CICE/ -> git status —> tells you what branch you are on and any commits that need to be made -> git branch —> tells you what branches are available locally -> git remote —v —> lists the remote sources. want “origin” to point to personal remote repo and “upstream” to point to the original code you forked from. -> git pull upstream master —> will fetch+merge any changes to the local master branch since you last stopped working on it. Need to specify “master” branch. If there are not changes it will tell you that you are already up-to-date can also do > git pull —rebase upstream master and the —rebase tells git to move your commits to the tip of the master branch after synchronizing with changes from central repository. Better to rebase than do a merge commit. Rebasing is unlikely to cause problems unless you’re working on the same code or feature as someone else. To stop this process just execute git rebase —abort. -- Make your local edits to *.rst files, code, etc. Then issue sphinx commands to test these. -> cd ../ (be in the /doc/ directory, not the source directory. Must be one directory up). -> make clean —> gets rid of old html -> make html —> makes new html from sphinx *.rst files. -> cd build/html -> open index.html (or other html code) —> opens html locally to check it quickly -- iterate on the steps above till you’re happy with the html code -- note that sometimes the math doesn't render properly the first time you try this. If this is the case, you should do another >make html and check it. If -that still doesn't work try just touching the *.rst file that isn't rendering properly (open it, save it, close it) and try >make html again. This has worked -in the past to get the math to render properly. At this time we are unsure why this is necessary. -> git status —> gives you list of files that are changed but not yet staged in red -> git add *.rst —> add *rst files or whatever else needs to be staged for documentation stuff. -> git status —> now should show list of changes that have been staged in green -> git commit -m “message” —> commit the changes to your local fork. This makes it ready to push to external fork. -> git push origin —> will push the local code changes to your remote “origin” fork. In this case the master fork with the *.rst files. Note that we set this up so that the push will ignore *.html files. -* note you may want to add the path for the documentation from gh-pages to the README.md file (or another file). The path is: https://duvivier.github.io/CICE/ (or use CICE-Consortium instead of duvivier for the consortium repository once the pull request is complete) - -2. Pushing *.html code in gh-pages branch -* Things to do once: -> cd ~/Documents/Research/github/CICE-Consortium/ -> git clone https://github.com/duvivier/CICE.git CICE.gh-pages -- note that this checks out the master branch. So we need to switch to the gh-pages branch. -> git checkout gh-pages -- This switches to the gh-pages branch, which *only* is used for html pages. - -* Things to do daily: -> cd ~/Documents/Research/github/CICE-Consortium/CICE.gh-pages/ -> git status —> check that you are on gh-pages branch with this tag. -> rm -rf . —> remove old html files in here -> cd ~/Documents/Research/github/CICE-Consortium/CICE/doc/ —> change to master branch -> make clean —> clean up old html code -> make html —> make the correct html code for *rst files you just committed to master branch -> cd build/html -> cp -r . ~/Documents/Research/github/CICE-Consortium/CICE.gh-pages/ -> cd ~/Documents/Research/github/CICE-Consortium/CICE.gh-pages/ -> git add . —> add the files to those needing a commit to local branch -> git commit -m “updates….” —> commit *.html files to local fork -> git push origin —> will push local changes to remote “origin” fork, which in this case is the gh-pages branch on my personal fork from the consortium. -- Check this online at personal pages to make sure it looks right, is pointing to right path, etc. etc. - -3. Merging with original repository -- Once you’ve checked and tested the documentation on your local fork, it’s time for a pull request to the original repository -- On personal GitHub webpage there is a button on left called “New Pull Request”. Click that. -- It then takes you to original repository (CICE-Consoritum/CICE/) from which you forked. It shows the number of changed files and the differences in green (additions) or red (subtractions) in these files with the files that exist on that branch. If you add a new file then everything is green. -- Once you’ve checked your code, then click the big, green “Create pull request” button and this will send the changes to the administrators of the CICE-Consoritum repository. (Elizabeth, Tony, Alice, others). -- Always issue a pull request to merge with the original repository rather than just merging it yourself. This is the main, well tested branch that we release from so we want multiple eyes to look everything over. This is less crucial for documentation than actual code, but still important.