Documentation cleanup

README.rst

@@ -1,7 +1,11 @@
-``pymorize``: A Python package to simplify do CMOR
-==================================================
+===============================================
+``pymorize``: A Python package to simplify CMOR
+===============================================
+
+-----
 
   ``pymorize`` is a Python package to simplify the standardization of output into the Climate Model Output Rewriter (CMOR) standard.
+
 .. image:: https://github.com/esm-tools/pymorize/actions/workflows/CI-test.yaml/badge.svg
     :target: https://github.com/esm-tools/pymorize/actions/workflows/CI-test.yaml
 .. image:: https://img.shields.io/pypi/v/pymorize.svg
@@ -10,18 +14,27 @@
 .. image:: https://readthedocs.org/projects/pymorize/badge/?version=latest
     :target: https://pymorize.readthedocs.io/en/latest/?badge=latest
     :alt: Documentation Status
-.. image:: https://img.shields.io/github/license/pgierz/pymorize
+.. image:: https://img.shields.io/github/license/esm-tools/pymorize
     :target: https://pymorize.readthedocs.io/en/latest/?badge=latest
+
 ------
 
 
-It "Makes CMOR Simple" :-) ``pymorize`` is designed as a wrapper around various CMORization tools and NetCDF command line tools to make reformatting data into CMIP6 compliant format as simple and flexible as possible.
+  "Makes CMOR Simple" :-) 
+
+``pymorize`` is designed as a wrapper around various CMORization tools and NetCDF 
+command line tools to make reformatting data into CMIP6 compliant format as simple
+and flexible as possible.
 
-The package is designed to be modular and extensible, with a plugin system that allows users to add their own subcommands to the main `pymorize` command line interface. The package is also designed to be used as a library, with a simple API that allows users to use the package in their own scripts. 
+The package is designed to be modular and extensible, with a plugin system that allows
+users to add their own subcommands to the main ``pymorize`` command line interface, as 
+well as including their own functionality to the standardization pipelines. The package is
+also designed to be used as a library, with a simple API that allows users to use the 
+package in their own scripts. 
 
 To get started, you can install it via ``pip``::
 
-    pip install git+https://github.com/pgierz/pymorize
+    pip install git+https://github.com/esm-tools/pymorize
 
 Then you can run the main command line interface. Start out by getting some help::
 
@@ -38,4 +51,7 @@ Licence
 Authors
 -------
 
-``pymorize`` was written by `Paul Gierz <pgierz@awi.de>`_, `Pavan Siligam <pavankumar.siligam@awi.de>`_.
+``pymorize`` was developed by the High Performance Computing and Data Processing group at
+the Alfred Wegener Institute for Polar and Marine Research, Bremerhaven, Germany. It was
+designed by `Paul Gierz <pgierz@awi.de>`_, and written by `Paul Gierz <pgierz@awi.de>`_ and
+`Pavan Siligam <pavankumar.siligam@awi.de>`_.

doc/conf.py

@@ -61,6 +61,7 @@
     "sphinx_rtd_theme",
     "sphinx_tabs.tabs",
     "sphinx_toolbox.collapse",
+    "sphinx.ext.intersphinx",
 ]
 
 # Strip the input promps for code cells when copying
@@ -70,6 +71,16 @@
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+intersphinx_mapping = {
+    "python": ("http://docs.python.org/", None),
+    "numpy": ("http://docs.scipy.org/doc/numpy/", None),
+    "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None),
+    "matplotlib": ("http://matplotlib.sourceforge.net/", None),
+    "pandas": ("http://pandas.pydata.org/pandas-docs/stable/", None),
+    "xarray": ("http://xarray.pydata.org/en/stable/", None),
+    "chemicals": ("https://chemicals.readthedocs.io/", None),
+}
+
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

doc/installation.rst

@@ -13,7 +13,7 @@ This is the most straightforward way to install the package if you don't need to
 
 You can also install the latest version from the repository by running::
 
-    pip install git+https://github.com/pgierz/pymorize.git
+  pip install git+https://github.com/esm-tools/pymorize.git
 
 If you want to ensure an isolated install and make sure nothing conflicts with other packages you have, and you **do not want to change source code**, you can have a look at 
 `pipx <https://pipx.pypa.io/stable/>`_.
@@ -23,5 +23,6 @@ From source
 
 If you want to modify the source code, you can install the package by cloning the repository and running::
 
-    git clone https://pgierz/pymorize.git
-    python setup.py install
+    git clone https://esm-tools/pymorize.git
+    cd pymorize
+    python -m pip install -e .

src/pymorize/units.py

@@ -24,7 +24,27 @@
 def handle_chemicals(
     s: Union[str, None] = None, pattern: Pattern = re.compile(r"mol(?P<symbol>\w+)")
 ):
-    """Registers known chemical elements definitions to global ureg (unit registry)"""
+    """Registers known chemical elements definitions to global ``ureg`` (unit registry)
+
+    Parameters
+    ----------
+    s: str or None
+        string to search for chemical elements based upon the symbol, e.g. ``C`` for carbon.
+    pattern: re.Pattern
+        compiled regex pattern to search for chemical elements. This should contain a
+        `named group <https://docs.python.org/3/howto/regex.html#non-capturing-and-named-groups>`_ ``symbol``
+        to extract the symbol of the chemical element from a potentially larger string.
+
+    Raises
+    ------
+    ValueError
+        If the chemical element is not found in the periodic table.
+
+    See Also
+    --------
+    ~chemicals.elements.periodic_table: Periodic table of elements
+    ~re.compile: `Python's regex syntax <https://docs.python.org/3/library/re.html#regular-expression-syntax>`_.
+    """
     if s is None:
         return
     match = pattern.search(s)
@@ -54,11 +74,13 @@ def handle_unit_conversion(
 
     If `source_unit` is provided, it is used instead of the unit from DataArray.
 
-    Parameters:
-    -----------
-    da: xr.DataArray
-    unit: unit to convert data to
-    source_unit: Override the unit on xr.DataArray if needed.
+    Parameters
+    ----------
+    da: ~xr.DataArray
+    unit: str
+        unit to convert data to
+    source_unit: str or None
+        Override the unit on ``da.attrs.unit`` if needed.
     """
     from_unit = da.attrs.get("units")
     if source_unit is not None: