Repository: NOAA-GFDL/xwmt (language: python)

Issue:
Documentation updates needed
A few to-dos:

- Establish a readthedocs site would be helpful with API referencing
- Ensure every function and class has a proper docstring
- Update `README.md`
- Add appropriate DOE and Princeton Acknowledgements


Discussion / hints:
This is a useful list. Where should we start? I think that all functions have a docstring except the low-level ones. If we remove the preprocessing routine we should have description on the required naming of the input dataset. Also @gmacgilchrist's description on the calculations would be useful to include (maybe in the readthedocs)?
A simple example with MOM6 output would add a necessary step after loading the data and before initializing the `swmt` class: Do a `xr.merge()` with the variables in `ds_vars` and grid info in `ds_static` and rename to the `xwmt` standard (CMOR?) naming:
```
ds = xr.merge([ds_vars,ds_static]).drop_dims(['xq','yq']).reset_coords(drop=True).rename({'xh': 'x', 'yh': 'y','geolat': 'lat', 'geolon': 'lon'})
```

Fix patch:
diff --git a/docs/source/conf.py b/docs/source/conf.py
index f9a972c..9e7a9ff 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -28,7 +28,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc','sphinx.ext.napoleon','IPython.sphinxext.ipython_console_highlighting',
-              'IPython.sphinxext.ipython_directive','jupyter_sphinx',
+              'IPython.sphinxext.ipython_directive','jupyter_sphinx','nbsphinx'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3833b49..7e4549e 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,7 +1,7 @@
-xWMT -- xarray-friendly Watermass Routines
-======================================================
+xWMT: xarray-friendly Water Mass Transformation analysis
+==========================================================
 
-**xwmt** is a package for analyzing watermass transformations from ocean model outputs
+**xwmt** is a Python package for water mass transformation analysis that leverages xarray functionality
 
 .. * :doc:`install`
 .. * :doc:`virtualenv`
@@ -51,15 +51,15 @@ xWMT -- xarray-friendly Watermass Routines
 
 Quick Install
 -------------
-To install from Anaconda:
+To install from PyPi:
 
 .. parsed-literal::
-   conda install -c jetesdal xwmt
+   pip install xwmt
 
-To install from PyPi:
+To install from GitHub:
 
 .. parsed-literal::
-   pip install xwmt
+   pip install git+https://github.com/NOAA-GFDL/xwmt.git
 
 .. Indices and tables
 .. ==================
diff --git a/docs/source/install.rst b/docs/source/install.rst
index f9597eb..94856db 100644
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@@ -1,11 +1,11 @@
 Installation
 ============
 
-**xwmt** xarray-friendly watermass transformation routines
+**xwmt** Python package for water mass transformation analysis that leverages xarray functionality
 
 Prerequisites and dependencies
 ------------------------------
-**xwmt** requires Python version 3.9 or greater and several additional pacakages
+**xwmt** requires Python version 3.9 or greater and several additional packages
 that are listed below:
 
 * Python >=3.9
@@ -15,3 +15,4 @@ that are listed below:
 * xgcm
 * xhistogram
 
+**xwmt** was build with `xgcm` version *0.5.2* and `xhistogram` version *0.1.1*. Some calculations may not work when a different version of `xgcm` or `xhistogram` is used.
diff --git a/docs/source/objective.rst b/docs/source/objective.rst
index a85ce9d..83996c5 100644
--- a/docs/source/objective.rst
+++ b/docs/source/objective.rst
@@ -1,5 +1,37 @@
+Introduction
+===========================
+
+The Water Mass Transformation (WMT) framework was initially put forward by `Walin (1982) <https://doi.org/10.1111/j.2153-3490.1982.tb01806.x>`_ to describe the relationship between surface heat fluxes and interior ocean circulation. A series of studies further refined the framework to include the effect of haline-driven buoyancy forcing (e.g., `Tziperman 1986 <https://doi.org/10.1175/1520-0485(1986)016%3C0680:OTROIM%3E2.0.CO;2>`_; `Speer and Tziperman, 1992 <https://doi.org/10.1175/1520-0485(1992)022%3C0093:ROWMFI%3E2.0.CO;2>`_) and account for the role of interior mixing (e.g., ` Nurser et al., 1999 <https://doi.org/10.1175/1520-0485(1999)029%3C1468:DWMFFA%3E2.0.CO;2>`_; `Iudicone et al., 2008 <https://journals.ametsoc.org/view/journals/phoc/38/7/2007jpo3464.1.xml>`_). A comprehensive overview of past studies in WMT and details of how WMT is derived from diapycnal processes can be found in `Groeskamp et al. 2019 <https://doi.org/10.1146/annurev-marine-010318-095421>`_).
+
+
 Package Objectives
 ===========================
+The goal of this package is to provide various WMT routines to derive key metrics related to water masses in the ocean.
+
+
+Required Input
+===========================
+The required input for the package is a xarray dataset including the necessary scalar field (e.g., ocean temperature, salinity or density) used for water mass classification and surface fluxes of heat, freshwater and salt. Varibale naming follows CMOR convention.
+- `tos`: Sea Surface Temperature (units: degC)
+> Temperature of upper boundary of the liquid ocean, including temperatures below sea-ice and floating ice shelves.
+- `sos`: Sea Surface Salinity (units: 0.001) 
+> Sea water salinity is the salt content of sea water, often on the Practical Salinity Scale of 1978. However, the unqualified term 'salinity' is generic and does not necessarily imply any particular method of calculation. The units of salinity are dimensionless and the units attribute should normally be given as 1e-3 or 0.001 i.e. parts per thousand. 
+- `hfds`: Downward Heat Flux at Sea Water Surface (units: W m-2)
+> This is the net flux of heat entering the liquid water column through its upper surface (excluding any "flux adjustment").
+- `wfo`: Water Flux into Sea Water (units: kg m-2 s-1)
+> Computed as the water flux into the ocean divided by the area of the ocean portion of the grid cell. This is the sum *wfonocorr* and *wfcorr*.
+- `sfdsi`: Downward Sea Ice Basal Salt Flux (units: kg m-2 s-1)
+> This field is physical, and it arises since sea ice has a nonzero salt content, so it exchanges salt with the liquid ocean upon melting and freezing.
+
+Surface WMT using `swmt` class
+==============================
+The first step is to initialize the class by creating an object. This object includes all the calculations for surface WMT (`swmt`) and full 3D WMT (`wmt`). Since we use here surface fluxes, we will use the `swmt` class.
+.. math::
+  swmt_class = swmt(ds)
 
-Beautiful wordy words go here ...
+The `swmt` class object includes multiple functions to look at the relevant data. The most common function is `.G()` which is the WMT along $\lambda$ (i.e., $G(\lambda)$). Here, we need to define $\lambda$. For example, 'theta' for potential temperature ($\theta$) or 'sigma0' for potential density referenced at 0 dbar ($\sigma_0$). You can use command `.lambdas()` for a list of available $\lambda$'s. Here, we will go with $\sigma_0$. This is all you need, but if you want to define the size of the bins you can do that with the argument `bin`.
+
+Disclaimer
+===========================
+`xwmt` does not employ any checks to ensure conservation of heat and salt. It is the user's responsibility to ensure that budgets for heat and salt are properly closed in the datasets. Improperly conserved fields will yield incorrect results.
 
diff --git a/xwmt/__init__.py b/xwmt/__init__.py
index ac8e17a..6df75cf 100644
--- a/xwmt/__init__.py
+++ b/xwmt/__init__.py
@@ -1,4 +1,4 @@
-""" xwmt: xarray-friendly watermass transformation """
+""" xwmt: xarray-friendly water mass transformation """
 
 from .swmt import swmt
 from .version import __version__


Test patch:
diff --git a/xwmt/tests/test_functional.py b/xwmt/tests/test_functional.py
index 6117531..d359fad 100644
--- a/xwmt/tests/test_functional.py
+++ b/xwmt/tests/test_functional.py
@@ -46,5 +46,4 @@ def test_functional_sigma0_notgrouped():
 ## xgcm
 def test_functional_sigma0_xgcm():
     total = xwmt.swmt(ds).G("sigma0",method="xgcm")
-    assert np.allclose(total.sum(), -2.1251855e09)
-
+    assert np.allclose(total.sum(), -2.1251855e09)
\ No newline at end of file