Merge pull request #12 from ocefpaf/docs

Docs

.travis.yml

@@ -1,7 +1,7 @@
 language: python
 
 env:
- - CONDA="python=2.7"
+ #- CONDA="python=2.7"
  - CONDA="python=3.4"
 
 before_install:

README.rst

@@ -20,8 +20,8 @@ The EOS-80 library is considered now obsolete; it is provided here for
 compatibility with old scripts, and to allow a smooth transition to the
 new `TEOS-10 <http://www.teos-10.org/>`__.
 
-Notes
------
+Warning
+-------
 
 The Python version default output unit for sw.dist is 'km' instead of
 'nm'.

docs/index.rst

@@ -3,66 +3,56 @@
  You can adapt this file completely to your liking, but it should at least
  contain the root `toctree` directive.
 
-Python Seawater
+python-seawater
 ===============
 
-|PyPI| |Build| |Downloads|
+.. image:: https://badge.fury.io/py/seawater.png
+ :target: http://badge.fury.io/py/seawater
+.. image:: https://api.travis-ci.org/pyoceans/python-seawater.png?branch=master
+ :target: https://travis-ci.org/pyoceans/python-seawater
+.. image:: https://zenodo.org/badge/doi/10.5281/zenodo.11395.png
+ :target: http://dx.doi.org/10.5281/zenodo.11395
+.. image:: http://bottlepy.org/docs/dev/_static/Gittip.png
+ :target: https://www.gittip.com/ocefpaf/
 
 This is a Python re-write of the CSIRO seawater toolbox
-(`SEAWATER-3.3 <http://www.cmar.csiro.au/datacentre/ext_docs/seawater.htm>`_)
-for calculating the properties of sea water.  The package uses the formulas
-from Unesco's joint panel on oceanographic tables and standards,
-UNESCO 1981 and UNESCO 1983 (EOS-80).
+(`SEAWATER-3.3 <http://www.cmar.csiro.au/datacentre/ext_docs/seawater.htm>`__)
+for calculating the properties of sea water. The package uses the
+formulas from Unesco's joint panel on oceanographic tables and
+standards, UNESCO 1981 and UNESCO 1983 (EOS-80).
 
 The EOS-80 library is considered now obsolete; it is provided here for
-compatibility with old scripts, and to allow a smooth transition to
-the new `TEOS-10 <http://www.teos-10.org/>`_.
-
-Before you start
-----------------
-
-The default output unit for sw.dist in the Python version is 'km' instead of
-'nm' as in the MatlabTM version.
-
-Also, we assume pressure as the first dimension, i.e. M pressure by N positions
-(See the table below). The MatlabTM version performs a series of guessing at
-that we simply ignored to avoid confusions.
-
-+--------+-----------+-----------+
-| P | S | T |
-+========+===========+===========+
-| 10 | 34.5487 | 28.7856 |
-+--------+-----------+-----------+
-| 50 | 34.7275 | 28.4329 |
-+--------+-----------+-----------+
-| 125 | 34.8605 | 22.8103 |
-+--------+-----------+-----------+
-| 250 | 34.6810 | 10.2600 |
-+--------+-----------+-----------+
-| 600 | 34.5680 | 6.8863 |
-+--------+-----------+-----------+
-| 1000 | 34.5600 | 4.4036 |
-+--------+-----------+-----------+
-| . | . | . |
-+--------+-----------+-----------+
-| . | . | . |
-+--------+-----------+-----------+
-| . | . | . |
-+--------+-----------+-----------+
-
-Check out the
-`test\_octave.py <https://github.com/ocefpaf/python-seawater/blob/master/test/test_octave.py>`_ script to test the Python library
-against an available MatlabTM library (all inside Python via the oct2py
-package). The current version was tested against seawater v3.3.
-
->>> python test_octave.py ./path_to_sewater_toolbox
-
-.. |PyPI| image:: https://badge.fury.io/py/seawater.png
- :target: http://badge.fury.io/py/seawater
-.. |Build| image:: https://api.travis-ci.org/ocefpaf/python-seawater.png?branch=master
- :target: https://travis-ci.org/ocefpaf/python-seawater
-.. |Downloads| image:: https://pypip.in/d/seawater/badge.png
- :target: https://crate.io/packages/seawater/
+compatibility with old scripts, and to allow a smooth transition to the
+new `TEOS-10 <http://www.teos-10.org/>`__.
+
+Warning
+-------
+
+The Python version default output unit for sw.dist is 'km' instead of
+'nm'.
+
+Here we assume pressure as the first dimension, i.e. M pressure by N
+positions (See the table below). The MatlabTM version does some guessing
+at this that we simply ignore to avoid confusions.
+
++---------+-----------+-----------+
+| **P** | **S** | **T** |
++=========+===========+===========+
+| 10 | 34.5487 | 28.7856 |
++---------+-----------+-----------+
+| 50 | 34.7275 | 28.4329 |
++---------+-----------+-----------+
+| 125 | 34.8605 | 22.8103 |
++---------+-----------+-----------+
+| 250 | 34.6810 | 10.2600 |
++---------+-----------+-----------+
+| 600 | 34.5680 | 6.8863 |
++---------+-----------+-----------+
+| 1000 | 34.5600 | 4.4036 |
++---------+-----------+-----------+
+
+The current version was tested against the MatlabTM seawater v3.3 reproducing
+all functions and results from that release.
 
 Documentation
 =============

seawater/eos80.py

@@ -119,7 +119,7 @@ def alpha(s, t, p, pt=False):
  Returns
  -------
  alpha : array_like
- thermal expansion coeff :math:`\alpha` [℃ :sup:`-1`]
+ thermal expansion coeff :math:`\\alpha` [℃ :sup:`-1`]
 
  Examples
  --------
@@ -141,7 +141,7 @@ def alpha(s, t, p, pt=False):
 
 def aonb(s, t, p, pt=False):
  """
- Calculate :math:`\alpha/\beta`.
+ Calculate :math:`\\alpha/\\beta`.
 
  Parameters
  ----------
@@ -157,7 +157,7 @@ def aonb(s, t, p, pt=False):
  Returns
  -------
  aonb : array_like
- :math:`\alpha/\beta` [psu ℃ :sup:`-1`]
+ :math:`\\alpha/\\beta` [psu ℃ :sup:`-1`]
 
  Examples
  --------
@@ -202,7 +202,7 @@ def aonb(s, t, p, pt=False):
 
 def beta(s, t, p, pt=False):
  """
- Calculate the saline contraction coefficient :math:`\beta` as defined
+ Calculate the saline contraction coefficient :math:`\\beta` as defined
  by T.J. McDougall.
 
  Parameters
@@ -644,7 +644,7 @@ def pden(s, t, p, pr=0):
  array([ 999.842594 , 999.79523994, 995.65113374, 996.36115932,
  1028.10633141, 1028.15738545, 1021.72863949, 1022.59634627])
 
- :math:`\sigma_{4}` (at 4000 db)
+ :math:`\\sigma_{4}` (at 4000 db)
 
  >>> sw.pden(s, t, p, 4000) - 1000
  array([ 19.2895493 , 19.33422519, 12.43271053, 13.27563816,
@@ -790,7 +790,7 @@ def salt(r, t, p):
  Parameters
  ----------
  r : array_like
- conductivity ratio :math:`R = \frac{C(S,T,P)}{C(35,15(IPTS-68),0)}`
+ conductivity ratio :math:`R = \\frac{C(S,T,P)}{C(35,15(IPTS-68),0)}`
  t : array_like
  temperature [℃ (ITS-90)]
  p : array_like
@@ -814,9 +814,9 @@ def salt(r, t, p):
 
  References
  ----------
- .. [1] Fofonoff, P. and Millard, R.C. Jr UNESCO 1983. Algorithms for
- computation of fundamental properties of seawater. UNESCO Tech. Pap. in
- Mar. Sci., No. 44, 53 pp. Eqn.(31) p.39.
+ .. [1] Fofonoff, P. and Millard, R.C. Jr UNESCO 1983.  Algorithms for
+ computation of fundamental properties of seawater. UNESCO Tech. Pap.
+ in Mar. Sci., No. 44, 53 pp. Eqn.(31) p.39.
  http://unesdoc.unesco.org/images/0005/000598/059832eb.pdf
 
  """

seawater/extras.py

@@ -92,13 +92,13 @@ def f(lat):
  Calculates the Coriolis factor :math:`f` defined by:
 
  .. math::
- f = 2 \Omega \sin(lat)
+ f = 2 \\Omega \\sin(lat)
 
  where:
 
  .. math::
- \Omega = \frac{2 \pi}{\textrm{sidereal day}} = 7.2921150e^{-5}
- \textrm{ radians sec}^{-1}
+ \\Omega = \\frac{2 \\pi}{\\textrm{sidereal day}} = 7.2921150e^{-5}
+ \\textrm{ radians sec}^{-1}
 
 
  Parameters

seawater/geostrophic.py

@@ -22,12 +22,12 @@ def bfrq(s, t, p, lat=None):
  depths from the equation:
 
  .. math::
- N^{2} = \frac{-g}{\sigma_{\theta}} \frac{d\sigma_{\theta}}{dz}
+ N^{2} = \\frac{-g}{\\sigma_{\\theta}} \\frac{d\\sigma_{\\theta}}{dz}
 
  Also calculates Potential Vorticity from:
 
  .. math::
- q=f \frac{N^2}{g}
+ q = f \\frac{N^2}{g}
 
  Parameters
  ----------

seawater/library.py

@@ -110,20 +110,20 @@ def cndr(s, t, p):
 
 def salds(rtx, delt):
  """
- Calculates Salinity differential (:math:`\frac{dS}{d(\sqrt{Rt})}`) at
+ Calculates Salinity differential (:math:`\\frac{dS}{d(\\sqrt{Rt})}`) at
  constant temperature.
 
  Parameters
  ----------
  rtx : array_like
- :math:`\sqrt{rt}`
+ :math:`\\sqrt{rt}`
  delt : array_like
  t-15 [℃ (IPTS-68)]
 
  Returns
  -------
  ds : array_like
- :math:`\frac{dS}{d rtx}`
+ :math:`\\frac{dS}{d rtx}`
 
  Examples
  --------
@@ -160,13 +160,13 @@ def salrp(r, t, p):
  Equation for Rp used in calculating salinity. UNESCO 1983 polynomial.
 
  .. math::
- Rp(S,T,P) = \frac{C(S,T,P)}{C(S,T,0)}
+ Rp(S,T,P) = \\frac{C(S,T,P)}{C(S,T,0)}
 
 
  Parameters
  ----------
  r : array_like
- conductivity ratio :math:`R = \frac{C(S,T,P)}{C(35,15(IPTS-68),0)}`
+ conductivity ratio :math:`R = \\frac{C(S,T,P)}{C(35,15(IPTS-68),0)}`
  t : array_like
  temperature [℃ (ITS-90)]
  p : array_like
@@ -175,7 +175,7 @@ def salrp(r, t, p):
  Returns
  -------
  rp : array_like
- conductivity ratio :math:`Rp(S,T,P) = \frac{C(S,T,P)}{C(S,T,0)}`
+ conductivity ratio :math:`Rp(S,T,P) = \\frac{C(S,T,P)}{C(S,T,0)}`
 
  Examples
  --------
@@ -210,7 +210,7 @@ def salrt(t):
  Equation for rt used in calculating salinity. UNESCO 1983 polynomial.
 
  .. math::
- rt(t) = \frac{C(35,t,0)}{C(35,15(\textrm{IPTS-68}), 0)}
+ rt(t) = \\frac{C(35,t,0)}{C(35,15(\\textrm{IPTS-68}), 0)}
 
 
  Parameters
@@ -329,7 +329,7 @@ def sals(rt, t):
  Parameters
  ----------
  rt : array_like
- :math:`rt(s,t) = \frac{C(s,t,0)}{C(35, t(\textrm{IPTS-68}), 0)}`
+ :math:`rt(s,t) = \\frac{C(s,t,0)}{C(35, t(\\textrm{IPTS-68}), 0)}`
  t : array_like
  temperature [℃ (ITS-90)]