Minor doc updates

docs/contributing.rst

@@ -0,0 +1,49 @@
+Contribution Guide
+=======================
+
+Contributions to ``pycoare`` of all forms are welcome!
+
+Please follow these guidelines for contributing to this project:
+
+* `Fork the pycoare repository into your local GitHub repository <https://github.com/pyCOARE/coare/fork>`_
+* Clone your forked repository to your local machine
+
+.. code-block:: bash
+
+    $ git clone <url_to_your_forked_repository>
+    $ cd coare
+
+* Install the development requirements in a new environment
+
+.. code-block:: bash
+
+    $ conda create -n pycoare
+    $ conda activate pycoare
+    $ pip install -r requirements-dev.txt
+
+* Create a new branch for your feature
+
+.. code-block:: bash
+
+    $ git checkout -b my-new-feature
+
+* Install the pre-commit hooks for code formatting
+
+.. code-block:: bash
+
+    $ pre-commit install
+
+* Make your changes and commit them
+
+.. code-block:: bash
+
+    $ git commit -am 'Add some feature'
+
+* Push to the branch
+
+.. code-block:: bash
+
+    $ git push origin my-new-feature
+
+* Create a new Pull Request on GitHub (a good title and description are helpful!)
+* A maintainer will review your changes and merge them into the main branch!

docs/index.rst

@@ -34,3 +34,7 @@ For more information on the people and publications that developed the COARE alg
 
     c35_api
     util_api
+
+.. toctree::
+
+    contributing

docs/usage.rst

@@ -1,56 +1,54 @@
 Usage
 =====
 
-.. _Usage:
-
-.. |fairall2003| replace:: COARE 3.0 code
-.. _fairall2003: https://doi.org/10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2
-.. |edson2013| replace:: CLIMODE, MBL and CBLAST experiments
-.. _edson2013: https://doi.org/10.1175/JPO-D-12-0173.1
-
-The COARE v3.5 algorithm is based on the |fairall2003|_ with modifications from the results of the |edson2013|_.
+This package is designed around an object oriented approach, since the number of parameters that the COARE algorithm outputs can be quite unwieldy otherwise.
+Therefore, the first step in using the COARE algorithm is to create an instance of the ``coare_35`` class:
 
-.. attention::
+    >>> from pycoare import coare_35  # import the coare_35 class
+    >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5])  # create instance of coare_35 class
 
-    Default values are included for the optional parameters (i.e., other than wind speed), but it is better to use available data for as many variables as possible.
-    If you must use a single measurement for any of the variables, try to use averages that are representative of the region of interest.
-    `See the API for more details <c35_api.html>`_.
+Note that this (and other examples in this documentation) uses *only* wind speed as input.
+This is bad practice, and ideally you should use as many input variables as possible.
+See :class:`~pycoare.coare_35` for a complete list of input variables.
 
 .. note::
 
     The COARE v3.5 algorithm can accept NumPy ``ArrayLike`` objects (e.g., ``float``, ``list``, ``numpy.ndarray``, etc.) as input.
     It is not yet designed to work with ``xarray`` objects (support coming soon).
     Please convert any ``xarray.DataArray`` to ``numpy.ndarray`` using the ``.values`` attribute before passing them to the COARE algorithm.
 
-This package is designed around an object oriented approach, since the number of parameters that the COARE algorithm outputs can be quite unwieldy otherwise.
-Therefore, the first step in using the COARE algorithm is to create an instance of the ``coare_35`` class.
-This instance takes wind speed as the primary argument, but can (and likely should) also take a myriad of additional parameters as keyword arguments.
-Here we show an example of how to use the COARE algorithm with only wind speed as input:
-
-    >>> from pycoare import coare_35  # import the coare_35 class
-    >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5])  # create instance of coare_35 class
-
 Once the ``coare_35`` object is created, the algorithm will automatically be ran.
-The output of the algorithm is stored in several subclasses, which can be accessed as attributes from the ``coare_35`` class.
-These subclasses should only ever be accessed from within a ``coare_35`` instance (as shown in the examples below).
-These classes contain "subattributes" that store the output of the algorithm, neatly divided into categories.
+The output of the algorithm is stored in several "output classes", which can be accessed as attributes from the ``coare_35`` class.
+Output classes contain "subattributes" that store the output of the algorithm, neatly divided into categories.
 
-For example, the ``fluxes`` attribute contains the output of the algorithm related to air-sea fluxes.
-To access the wind stress (i.e. the air-sea momentum flux), the you can use the ``tau`` subattribute of the ``fluxes`` attribute of the ``coare_35`` object:
+For example, the ``fluxes`` output class contains the output of the algorithm related to air-sea fluxes.
+To access the wind stress (i.e. the air-sea momentum flux), you can use the ``tau`` subattribute of the ``fluxes`` attribute of the ``coare_35`` object:
 
     >>> from pycoare import coare_35
-    >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5])  # same as above example, algorithm is run only once
+    >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5])  # create instance of coare_35 class
     >>> c.fluxes.tau  # access the wind stress
     array([0.        , 0.00060093, 0.00165957, 0.00319516, 0.00520412, 0.00768739])
 
-As another example, the ``transfer_coefficients`` attribute contains the output of the algorithm related, unsurprisingly, to transfer coefficients.
+.. important::
+
+    These "output classes" should only ever be accessed from within a ``coare_35`` instance (as shown in the examples).
+
+As another example, the ``transfer_coefficients`` output class contains the output of the algorithm related, unsurprisingly, to transfer coefficients.
 To access the neutral wind stress transfer coefficient (i.e., neutral drag coefficient), you can use the ``cdn_rf`` subattribute of the ``transfer_coffiencient`` attribute of the ``coare_35`` object:
 
     >>> from pycoare import coare_35
-    >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5])  # same as above example, algorithm is run only once
-    >>> c.transfer_coefficients.cdn_rf  # access the wind stress
+    >>> c = coare_35([0.0, 0.5, 1.0, 1.5, 2.0, 2.5])  # create instance of coare_35 class
+    >>> c.transfer_coefficients.cdn_rf  # access the drag coefficient
     array([1.2360058 , 1.12526078, 1.04170881, 0.98860156, 0.95127555, 0.92438611])
 
-The available attribute classes accesseible from a ``coare_35`` instance are:
-:class:`fluxes`, :class:`transfer_coefficients`, :class:`stability_functions`, :class:`velocities`, :class:`temperatures`, and :class:`humidities`.
-A full list of the available subattributes and a brief description of them can be found in the complete `COARE v3.5 API documentation <c35_api.html>`_.
+The available output classes accessible from a :class:`~pycoare.coare_35` instance are:
+
+* :class:`~pycoare.coare_35.fluxes`
+* :class:`~pycoare.coare_35.transfer_coefficients`
+* :class:`~pycoare.coare_35.stability_functions`
+* :class:`~pycoare.coare_35.velocities`
+* :class:`~pycoare.coare_35.temperatures`
+* :class:`~pycoare.coare_35.humidities`
+
+The links above will take you to the documentation for each of these output classes.
+This contains information on the subattributes that are available in each output class.

pycoare/coare_35.py

@@ -21,6 +21,19 @@
 
 class coare_35:
     """
+    .. |fairall2003| replace:: COARE 3.0 code
+    .. _fairall2003: https://doi.org/10.1175/1520-0442(2003)016<0571:BPOASF>2.0.CO;2
+    .. |edson2013| replace:: CLIMODE, MBL and CBLAST experiments
+    .. _edson2013: https://doi.org/10.1175/JPO-D-12-0173.1
+
+    The COARE v3.5 algorithm is based on the |fairall2003|_ with modifications from the results of the |edson2013|_.
+
+    Usage example using only wind speed as an input (see note above)::
+
+        from pycoare import coare_35
+        # creating a coare_35 instance
+        c = coare_35([1])
+
     :param u: ocean surface wind speed (m/s) at height zu
     :type u: ArrayLike
     :param t: bulk air temperature (degC) at height zt