Merge pull request #35 from DocOtak/docs

Add attr table to docs

Author: DocOtak

.gitignore

@@ -1,3 +1,6 @@
+# These files are generated on doc build and shoudl not be kept in VC
+docs/_attr_table.rst
+
 # macOS noise
 .DS_Store
 

README.rst

@@ -11,6 +11,7 @@ gsw-xarray: Wrapper for gsw that adds CF attributes
 
 gsw-xarray is a wrapper for `gsw python <https://github.com/TEOS-10/GSW-python>`_
 that will add CF attributes to xarray.DataArray outputs.
+It is meant to be a drop in wrapper for the upstream GSW-Python library and will only add these attributes if one argument to a function is an xarray.DataArray.
 
 Usage
 -----
@@ -40,6 +41,19 @@ Outputs
 
    {'standard_name': 'sea_water_sigma_t', 'units': 'kg/m^3'}
 
+Don't worry about usage with non xarray array objects, just use in all places you would the upstream library:
+
+.. code:: python
+
+   sigma0 = gsw.sigma0(id * 10, id * 0.1 + 34)
+   print(type(sigma0), sigma0)
+
+Outputs
+
+::
+
+   <class 'numpy.ndarray'> [-5.08964499  2.1101098   9.28348219]
+
 Installation
 ------------
 Pip
@@ -54,7 +68,7 @@ Conda
 .....
 
 For the moment gsw-xarray is not released in conda-forge, so you'll
-need to instal via pip: activate your conda environment, and then use ``pip install gsw_xarray``.
+need to install via pip: activate your conda environment, and then use ``pip install gsw_xarray``.
 
 Pipenv
 ......
@@ -68,7 +82,7 @@ Contributor guide
 All contributions, bug reports, bug fixes, documentation improvements,
 enhancements, and ideas are welcome.
 If you notice a bug or are missing a feature, fell free
-to open an issue in the `github issues page <https://github.com/DocOtak/gsw-xarray/issues>`_.
+to open an issue in the `GitHub issues page <https://github.com/DocOtak/gsw-xarray/issues>`_.
 
 In order to contribute to gsw-xarray, please fork the repository and
 submit a pull request. A good step by step tutorial for starting with git can be found in the

docs/attrs.rst

@@ -0,0 +1,23 @@
+Added Attributes
+================
+This rather long list shows all the attributes that will be set on the returned DataArray objects and their exact value.
+
+There are some things to be aware of:
+
+* Functions which return unitless values will have the ``units`` attribute set to ``"1"`` following the CF recommended practice (based on SI).
+  Rather than omit the ``units`` attribute entirely, we want to explicitly state that something is unitless.
+
+* The unit strings were selected to be compatible with both UDUNITS2 (the requirement in CF), and the python pint library.
+
+* Not every returned value has a CF standard name, in which case we must not include the standard name attribute.
+  As names are added to the CF table, we will attempt to update this list.
+  The current standard names were taken from v78 last published on 2021-09-21.
+
+  Additionally, some standard names are only valid for specific input values e.g. z_from_p has geopotential parameters and the normal standard name does not apply if these are not 0.
+
+* We include the OceanSITES ``reference_scale`` attribute for functions that return PSS-78 or ITS-90.
+
+* Finally, we did our best to include the correct units and standard name based on the published TEOS-10 documentation.
+  If errors are noted, please open an issue on GitHub so we can correct these errors.
+
+.. include:: _attr_table.rst

docs/conf.py

@@ -27,7 +27,11 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    "sphinx.ext.autosectionlabel",
+]
+
+autosectionlabel_prefix_document = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -49,3 +53,11 @@
 # 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"]
+
+
+try:
+    exec(open("gen_attr_table.py").read())
+except NameError:
+    from runpy import run_path
+
+    run_path("gen_attr_table.py")

docs/gen_attr_table.py

@@ -0,0 +1,39 @@
+from sphinx.util import progress_message
+
+from gsw_xarray._names import _names
+from gsw_xarray._attributes import _func_attrs
+
+list_table = ""
+
+
+def _add_attrs(list_table, attrs, label):
+    if (label_value := attrs.get(label)) is not None:
+        list_table += f"   * {label}: ``{label_value}``\n"
+
+    return list_table
+
+
+with progress_message("Generating gsw attribute table"):
+    for name, result_name in _names.items():
+        list_table += f"{name}\n{'-' * len(name)}\n"
+        if isinstance(result_name, tuple):
+            list_table += f"Has {len(result_name)} outputs\n\n"
+            for i, result in enumerate(result_name):
+                list_table += f"#. **{result}**\n\n"
+                attrs = _func_attrs[name][i]
+                list_table = _add_attrs(list_table, attrs, "standard_name")
+                list_table = _add_attrs(list_table, attrs, "units")
+                list_table = _add_attrs(list_table, attrs, "reference_scale")
+                list_table += "\n"
+
+        else:
+            attrs = _func_attrs[name]
+            list_table += "Has 1 output\n\n"
+            list_table += f"#. **{result_name}**\n\n"
+            list_table = _add_attrs(list_table, attrs, "standard_name")
+            list_table = _add_attrs(list_table, attrs, "units")
+            list_table = _add_attrs(list_table, attrs, "reference_scale")
+        list_table += "\n"
+
+    with open("_attr_table.rst", "w", encoding="utf8") as f:
+        f.write(list_table)

docs/index.rst

@@ -3,24 +3,17 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to gsw-xarray's documentation!
-======================================
+.. include:: ../README.rst
 
-``gsw-xarray`` is an xarray aware wrapper of the functions contained in ``GSW-Python``.
-It will add CF the appropriate CF Standard Name (when one exists) and unit attributes to the resulting Dataarray.
-
-Installation
-------------
-``gsw-xarray`` can be installed with pip
-
-.. code:: shell
-
-   pip install gsw-xarray
+For the specific list of what attributes are added for each function, see the :ref:`attrs:Added Attributes` section.
 
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+
+   attrs
 
 
 

gsw_xarray/_names.py

@@ -2,8 +2,8 @@
     "CT_first_derivatives": ("CT_SA", "CT_pt"),
     "CT_first_derivatives_wrt_t_exact": ("CT_SA_wrt_t", "CT_T_wrt_t", "CT_P_wrt_t"),
     "CT_freezing": "CT_freezing",
-    "CT_freezing_first_derivatives": ("CTfreezing_SA", "CTfreezing_P"),
-    "CT_freezing_first_derivatives_poly": ("CTfreezing_SA", "CTfreezing_P"),
+    "CT_freezing_first_derivatives": ("CT_freezing_SA", "CT_freezing_P"),
+    "CT_freezing_first_derivatives_poly": ("CT_freezing_SA", "CT_freezing_P"),
     "CT_freezing_poly": "CT_freezing",
     "CT_from_enthalpy": "CT",
     "CT_from_enthalpy_exact": "CT",