Add documentation instructions to readme

README.md

@@ -1,44 +1,64 @@
-<img src="share/pcmdi/PMPLogo_1359x1146px_300dpi.png" width="15%" height="15%" align="right" />
-<h5 align="right"></h5> 
-
-PCMDI metrics package (PMP)
-======
-[![stable version](https://img.shields.io/badge/stable%20version-1.2-brightgreen.svg)](https://github.com/PCMDI/pcmdi_metrics/releases/tag/1.2)
-![platforms](https://img.shields.io/badge/platforms-linux%20|%20osx-lightgrey.svg)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.809463.svg)](https://doi.org/10.5281/zenodo.809463)
-[![Anaconda-Server Badge](https://anaconda.org/pcmdi/pcmdi_metrics/badges/installer/conda.svg)](https://conda.anaconda.org/pcmdi)
-[![Anaconda-Server Badge](https://anaconda.org/pcmdi/pcmdi_metrics/badges/downloads.svg)](https://anaconda.org/pcmdi/pcmdi_metrics)
-[![CircleCI](https://circleci.com/gh/PCMDI/pcmdi_metrics.svg?style=svg)](https://circleci.com/gh/PCMDI/pcmdi_metrics)
-[![Coverage Status](https://coveralls.io/repos/github/PCMDI/pcmdi_metrics/badge.svg)](https://coveralls.io/github/PCMDI/pcmdi_metrics)
-
-The PCMDI metrics package is used to provide "quick-look" objective comparisons of Earth System Models (ESMs) with one another and available observations. Results are produced in the context of all model simulations contributed to CMIP6 and earlier CMIP phases. Among other purposes, this enables modeling groups to evaluate changes during the development cycle in the context of the structural error distribution of the multi-model ensemble. Currently, the comparisons emphasize metrics of large- to global-scale annual cycle and both tropcial and extra-tropical modes of variability. Ongoing work in v1.x development branches include established statistics for ENSO, MJO, regional monsoons, and high frequency characteristics of simulated precipitation. 
-
-**PCMDI uses the PMP to produce [quick-look simulation summaries across generations of CMIP](https://cmec.llnl.gov/results/physical.html)** 
-
-The metrics package consists of four parts: 1) Analysis software, 2) an observationally-based database of global (or near global, land or ocean) annual cycle climatologies, 3) a database of performance metrics computed for CMIP models and 4) package documentation (in preparation).
-
-The package expects model data to be [CF-compliant](http:https://cfconventions.org/). To successfully use the package some input data "conditioning" may be required. We provide several demo scripts within the package.
-
-Users of the current release (v1.2) will need to contact the PMP developers ([email protected]) to obtain supporting datasets and get started using the package.
-
-
-GETTING STARTED
+gh-pages
+This branch hosts the online documentation for the PCMDI Metrics packages.
+
+Instructions for updating documentation:
+
+Checking out and making changes to the docs branch:
+---------------------------------------------------
+
+You must be in a conda environment with "sphinx" and "sphinx_rtd_theme" installed
+```
+git checkout -b gh-pages
+git pull origin gh-pages (optional, grab latest updates)
+git checkout -b <new branch name>
+cd docs
+```
+The source files are found in pcmdi_metrics/docs/source. There is an index.rst file that is the landing page. If you create a new page, make sure to list it under the toctree in index.rst.
+
+Building for local preview
+--------------------------
+```
+cd pcmdi_metrics/docs
+make clean
+make html
+```
+The `make clean` command is optional and deletes the existing docs/build folder, which is populated by `make html`.
+To view your changes locally, open pcmdi_metrics/docs/build/html/index.html with a browser. If it does not build as expected, first try running "make clean" before building again.
+
+Build for github
 ----------------
-
-Installation requirements and instructions are available on the [Install](https://github.com/PCMDI/pcmdi_metrics/wiki/Install-using-Anaconda) page
-
-An overview for using the package and template scripts are detailed on the [Using-the-package](https://github.com/PCMDI/pcmdi_metrics/wiki/Using-the-package) page
-
-Some installation support for CMIP participating modeling groups is available: [email protected]
-
-PMP versions
-------------
-
-v1.2 - Tied to CDAT 8.0. Now includes extensive regression testing. New metrics: Diurnal cycle and intermittency of precipitation, Sperber and Wang Monsoon metrics
-
-v1.1.2 - Now managed through Anaconda, and tied to UV-CDAT 2.10. Weights on bias statistic added. Extensive provenance information incorporated into json files.
-
-v1.1 - First public release, emphasizing climatological statistics, with development branches for ENSO and regional monsoon precipitation indices
-
-v1.0 - Prototype version of the PMP
-
+The main difference here is that the web files have to be copied to /docs. There is a command that does builds and copies in one step:
+```
+cd pcmdi_metrics/docs
+make github
+```
+Alternatively, these are the manual steps to build for github:
+```
+cd pcmdi_metrics/docs
+make clean
+make html
+cp -r build/html/* . 
+```
+After building, you then have to "git add" all the files you copied from build/html and commit before pushing. This includes \*html, \*inv, and \*js files, along with the _sources and _static folders (which are currently listed in .gitignore, so you have to make sure to add them)
+For example:
+```
+git add source/*rst *html *inv *js _static _sources
+git commit -m "your message"
+```
+Then you can push your changes
+
+Pushing your changes to your fork to preview:
+---------------------------------------------
+In pcmdi_metrics, set up your fork as a remote:
+```
+git remote add <remote name> <https://github.com/your_fork_path>
+git remote -v
+```
+Checkout and push your changes:
+```
+git checkout <branch with changes>
+git push <remote name> <branch with changes>
+```
+Then go to your forked repo on github.com. Go to Settings -> GitHub Pages -> Source. Under source, select the name of the branch you just pushed. Choose /docs as the folder. This will generate a link to your github pages site.
+
+You can also open a pull request from your fork repo, if desired.