Merge pull request #938 from PCMDI/gh-pages-re-org

Simplify docs generating process

.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+ os: ubuntu-22.04
+ tools:
+ python: "3.11"
+ # You can also specify other tool versions:
+ # nodejs: "19"
+ # rust: "1.64"
+ # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+ configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+# - pdf
+# - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+# install:
+# - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = python -msphinx
+SPHINXPROJ = pcmdi_metrics
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,49 @@
+gh-pages
+--------
+This branch hosts the online documentation for the PCMDI Metrics packages. Provided here are instructions for updating the 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 pull origin main (optional, grab latest updates)
+git checkout -b <new branch name>
+cd docs
+```
+The source files are found in pcmdi_metrics/docs/. 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 readthedocs
+---------------------
+After building, you then have to "git add" all the files you updated.
+
+For example:
+```
+git add *rst _static/*
+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 and create a Pull Request to the `main` branch. Once merged, readthedocs webhook will automatically generate the web pages.

docs/conf.py

@@ -0,0 +1,93 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+import sphinx_autosummary_accessors
+
+# -- Project information -----------------------------------------------------
+
+project = 'PCMDI Metrics Package'
+copyright = '2023 PCMDI'
+author = 'PCMDI'
+
+# The full version, including alpha/beta/rc tags
+# release = '1.2.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+
+html_theme = "sphinx_book_theme"
+
+# 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.
+#
+# sphinx_book_theme configurations
+# https://sphinx-book-theme.readthedocs.io/en/latest/configure.html
+html_logo = "_static/PMPLogo_500x421px_72dpi.png"
+html_title = "PMP Documentation"
+html_theme_options = {
+ "repository_url": "https://github.com/PCMDI/pcmdi_metrics",
+ "repository_branch": "main",
+ "path_to_docs": "docs",
+ "use_edit_page_button": True,
+ "use_repository_button": True,
+ "use_issues_button": True,
+ "use_download_button": True,
+ "use_fullscreen_button": True,
+}
+
+"""
+import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+"""
+
+# 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,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,90 @@
+.. pcmdi_metrics documentation master file, created by
+ sphinx-quickstart on Wed Nov 4 13:15:37 2020.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+***************************
+PCMDI Metrics Package (PMP)
+***************************
+
+The Program for Climate Model Diagnosis & Intercomparison (`PCMDI`_) Metrics Package (PMP) 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. 
+Currently, the comparisons emphasize metrics of large- to global-scale annual cycle and both tropcial 
+and extra-tropical modes of variability. 
+Recent release (v3) include established statistics for mean climate, ENSO, MJO, extratropical modes of variability, 
+regional monsoons, and high frequency characteristics of simulated precipitation as a part of U.S. DOE's Benchmarking of simulated precipitation. 
+
+`PCMDI`_ uses the PMP to produce `quick-look simulation summaries across generations of CMIP <https://pcmdi.llnl.gov/metrics>`_.
+
+The PMP expects model data to be `CF-compliant <http:https://cfconventions.org/>`_, otherwise, 
+to successfully use the package may require some input data conditioning. 
+It is also strongly suggested to work with observation datasets following the `CF-compliant <http:https://cfconventions.org/>`_, 
+such as datasets from the `obs4MIPs`_ project. 
+
+
+Getting Started
+===============
+Installation requirements and instructions are available on the :ref:`install` page
+
+An overview of the summary statistics available via the package 
+are summarized with interactive Jupyter notebooks in the :ref:`metrics` page
+
+Some installation support for CMIP participating modeling groups is available: [email protected]
+
+
+Acknowledgement
+===============
+
+Huge thank you to all of the PMP `contributors`_!
+
+.. _contributors: https://github.com/PCMDI/pcmdi_metrics#contributors
+
+PMP is developed by scientists and developers from the Program for Climate Model Diagnosis and
+Intercomparison (`PCMDI`_) at Lawrence Livermore National Laboratory (`LLNL`_). 
+This work is sponsored by the Regional and Global Model Analysis (`RGMA`_) program of 
+the Earth and Environmental Systems Sciences Division (`EESSD`_) in 
+the Office of Biological and Environmental Research (`BER`_) 
+within the `Department of Energy`_'s `Office of Science`_. 
+The work is performed under the auspices of the U.S. Department of Energy by 
+Lawrence Livermore National Laboratory under Contract DE-AC52-07NA27344.
+
+.. _LLNL: https://www.llnl.gov/
+.. _PCMDI: https://pcmdi.llnl.gov/
+.. _RGMA: https://climatemodeling.science.energy.gov/program/regional-global-model-analysis
+.. _EESSD: https://science.osti.gov/ber/Research/eessd
+.. _BER: https://science.osti.gov/ber
+.. _Department of Energy: https://www.energy.gov/
+.. _Office of Science: https://science.osti.gov/
+.. _obs4MIPs: https://pcmdi.github.io/obs4MIPs/
+
+
+License
+=======
+
+BSD 3-Clause License. See `LICENSE <https://github.com/PCMDI/pcmdi_metrics/blob/main/LICENSE>`_ for details
+
+.. toctree::
+ :maxdepth: 1
+ :hidden:
+ :caption: For users:
+
+ overview
+ start
+ metrics
+ Results <https://pcmdi.llnl.gov/research/metrics/>
+
+.. toctree::
+ :maxdepth: 1
+ :hidden:
+ :caption: For developers/contributors:
+
+ resources
+ team
+ GitHub repository <https://github.com/PCMDI/pcmdi_metrics>
+
+.. toctree::
+ :maxdepth: 1
+ :hidden:
+ :caption: Community
+
+ GitHub discussions <https://github.com/PCMDI/pcmdi_metrics/discussions>

docs/install.rst

@@ -0,0 +1,61 @@
+.. _install:
+
+**********************
+Installation
+**********************
+
+We offer an installation for `Anaconda`_ users under linux-64 or osx-64. 
+Support for Windows is not available yet.
+
+https://anaconda.org/conda-forge/pcmdi_metrics
+
+All Platforms System Requirements
+=================================
+ * Install the `Anaconda`_ package (we recommend installing this for each user)
+ * Alternatives include `Miniconda`_ or `Miniforge/Mambaforge`_
+ * If using Anaconda or Miniconda, we recommend also installing `mamba`_ for better performance
+
+ * Make sure anaconda is in your PATH (assuming anaconda is installed in ${HOME}/anaconda
+ * ``export PATH=${HOME}/anaconda/bin:${PATH}`` # for [ba]sh
+ * ``setenv PATH ${HOME}/anaconda/bin:${PATH}`` # for [t]csh
+
+Make sure you have no environment variables set from an old UV-CDAT installation in your PATH/PYTHONPATH,LD_LIBRARY_PATH etc
+
+
+Install PMP using conda/mamba
+==========================================
+You can install the PCMDI Metrics package from the PCMDI conda-forge channel. 
+For the best performance, use `mamba`_. 
+For faster installation without mamba, specify versions of python and pcmdi_metrics.
+
+Create a new virtual environment and install PMP
+ * Using `mamba`_ 
+ * ``mamba create -n [YOUR_CONDA_ENVIRONMENT] -c conda-forge pcmdi_metrics`` 
+
+ * Using `conda`_
+ * ``conda create -n [YOUR_CONDA_ENVIRONMENT] -c conda-forge python=[VERSION] pcmdi_metrics=[VERSION]`` 
+ * e.g. ``conda create -n pcmdi_metrics -c conda-forge python=3.10 pcmdi_metrics=3.0.1`` 
+
+ * Using `conda`_ (alternative)
+ * ``conda create -n [YOUR_CONDA_ENVIRONMENT]``
+ * ``conda activate [YOUR_CONDA_ENVIRONMENT]``
+ * ``conda install -c conda-forge python=[VERSION] pcmdi_metrics=[VERSION]``
+
+ * (Another alternative) Install PMP in the current (or existing) virtual environment
+ * Using `mamba`_: ``mamba install -c conda-forge pcmdi_metrics``
+ * or using `conda`_: ``conda install -c conda-forge pcmdi_metrics``
+
+To learn more about conda environments see: http:https://conda.pydata.org/docs/using/envs.html
+
+.. _mamba: https://mamba.readthedocs.io/en/latest/installation.html
+.. _Miniforge/Mambaforge: https://github.com/conda-forge/miniforge
+.. _Miniconda: https://conda.io/miniconda.html
+.. _Anaconda: https://www.anaconda.com/products/individual#Downloads
+.. _conda: https://docs.conda.io/en/latest/
+
+
+Bypassing firewalls (optional)
+==============================
+If your institution has tight ssl certificate/security issues try before installing PMP:
+ * ``conda config --set ssl_verify False``
+ * ``binstar config --set ssl_verify False``

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http:https://sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd