Doc with book

CHANGES.rst

@@ -6,13 +6,14 @@ Current
 
 New features
 ------------
-- Call :func:`xoa.cf.infer_cf_specs` from :func:`xoa.cf.get_cf_specs`  when an data arrray or dataset is passed.
+- Call :func:`xoa.cf.infer_cf_specs` from :func:`xoa.cf.get_cf_specs`  when an data arrray or dataset is passed [:pull:`96`].
 - Add the `drop_na` and `maxgap` parameters to the :func:`xoa.regrid.regrid1d` function to fill gaps [:pull:`92`].
 - Add the :func:`xoa.filter.tidal_filter` function to apply a tidal filter to time serie [:pull:`87`].
 
 Breaking changes
 ----------------
-- The default `name_format` option of the :cfsec:`sglocator` Cf specication option is set to False to prvent parsing the grid location in names.
+- The :meth:`xoa.cf.CFSpecs.decode` no longer sets the "cf_specs" encoding [:pull:`96`].
+- The default `name_format` option of the :cfsec:`sglocator` Cf specication option is set to False to prevent parsing the grid location in names [:pull:`96`].
 - :func:`xoa.filter.tidal_filter` raises an :class:`~xoa.XoaError` instead of a simple warning when the time step is greater than an hour.
 - :func:`xoa.regrid.regrid1d`: extrapolation from input data instead of output data [:pull:`91`].
 
@@ -22,6 +23,7 @@ Deprecations
 
 Bug fixes
 ---------
+- Fix `xoa.cf.infer_cf_specs` that was mising attributes and encoding [:pull:`96`].
 - Fix `lat` keyword in :func:`~xoa.geo.deg2m` and :func:`~xoa.geo.m2deg` which now accepts arrays.
 - Fix weighting of :func:`xoa.filter.convolve`.
 - Fix :func:`xoa.grid.to_rect` raising of errors and handling of missing data in coordinates.
@@ -30,7 +32,7 @@ Bug fixes
 
 Documentation
 -------------
-
+- Now using `Sphinx book theme <https://sphinx-book-theme.readthedocs.io/en/stable/#>`_
 
 0.7.1 (2023-07-21)
 ==================

README.rst

@@ -13,10 +13,10 @@ xoa - xarray-based ocean analysis library
     :alt: Documentation Status
     :target: https://xoa.readthedocs.io/en/latest/
 .. image:: https://anaconda.org/conda-forge/xoa/badges/downloads.svg
-    :alt: Number of downloads on anaconda.org/conda-forge
+    :alt: Total number of downloads on anaconda.org/conda-forge
     :target: https://anaconda.org/conda-forge/xoa/
-.. image:: https://pepy.tech/badge/xoa
-    :alt: Number of downloads on pypi
+.. image:: https://img.shields.io/pypi/dm/xoa
+    :alt: PyPI - Downloads
     :target: https://pypi.org/project/xoa
 .. image:: https://img.shields.io/badge/code%20style-black-black
     :alt: Black code style

doc/conf.py

@@ -21,7 +21,7 @@
 # %% Project information
 
 project = 'xoa'
-copyright = '2020-2022, Shom'
+copyright = '2020-2024, Shom'
 author = 'Shom'
 
 # The full version, including alpha/beta/rc tags
@@ -49,6 +49,7 @@
     "IPython.sphinxext.ipython_console_highlighting",
     'genoptions',
     'gencfspecs',
+    'genlogos',
     'sphinxarg.ext',
     'sphinxcontrib.programoutput',
     'sphinx_autosummary_accessors',
@@ -74,13 +75,27 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_book_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # 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']
 
+html_theme_options = {
+    "logo": {
+        "image_light": "_static/xoa-logo-light.png",
+        "image_dark": "_static/xoa-logo-dark.png",
+    },
+    "repository_url": "https://github.com/shom-fr/xoa",
+    "repository_branch": "develop",
+    "use_repository_button": True,
+    "use_issues_button": True,
+    "use_source_button": True,
+    "path_to_docs": "doc/",
+}
+
+
 # %% Autosumarry
 autosummary_generate = True
 
@@ -93,10 +108,9 @@
     'numba:': ('https://numba.readthedocs.io/en/stable/', None),
     'numpy': ("https://numpy.org/doc/stable/", None),
     'pandas': ('https://pandas.pydata.org/docs/', None),
-    'proplot': ('https://proplot.readthedocs.io/en/latest/', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
     'xarray': ('http://xarray.pydata.org/en/stable/', None),
-    'gsw': ('https://teos-10.github.io/GSW-Python', None)
+    'gsw': ('https://teos-10.github.io/GSW-Python', None),
     # 'xesmf': ("https://xesmf.readthedocs.io/en/latest/", None)
 }
 

doc/ext/genlogos.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+To generate the xoa logos
+"""
+import os
+import logging
+
+import matplotlib
+import matplotlib.pyplot as plt
+import matplotlib.patches as mpatches
+import matplotlib.transforms as mtransforms
+
+shomlightblue = (90, 194, 231)
+shomdarkblue = (0, 36, 84)
+
+
+def genlogo(outfile, dark=False):
+    """Generate a xoa logo and save it"""
+    font = "Cantarell"
+    # font = "Noto sans"
+    width, height = (4, 2.7)
+
+    if dark:
+        fontcolor = "w"
+    else:
+        fontcolor = tuple(c / 255 for c in shomdarkblue)
+    circlecolor = tuple(c / 255 for c in shomlightblue)
+
+    with plt.rc_context({"font.sans-serif": [font]}):
+        plt.figure(figsize=(width, height))
+        ax = plt.axes([0, 0, 1, 1], aspect=1, facecolor="b")
+        kw = dict(
+            family="sans-serif",
+            size=100,
+            color=fontcolor,
+            va="center_baseline",
+            weight="extra bold",
+            transform=ax.transAxes,
+        )
+        ax.text(0.05, 0.5, "X", ha="left", **kw)
+        ax.text(0.95, 0.5, "A", ha="right", **kw)
+        plt.xlim(0, width)
+        plt.ylim(0, height)
+
+        clip_height = 0.26
+        for y0 in (0, 1 - clip_height):
+            circle = mpatches.Circle(
+                (width / 2, height / 2),
+                radius=height * 0.5 * 0.81,
+                facecolor="none",
+                linewidth=14,
+                ec=circlecolor,
+            )
+
+            ax.add_patch(circle)
+
+            clip = mtransforms.TransformedBbox(
+                mtransforms.Bbox([[0, y0], [1, y0 + clip_height]]), ax.transAxes
+            )
+            circle.set_clip_box(clip)
+
+        ax.axis("off")
+        plt.savefig(outfile, transparent=True)
+
+
+def genlogos(app):
+    """Generate light and dark xoa logo during doc compilation"""
+    srcdir = app.env.srcdir
+    gendir = os.path.join(srcdir, "_static")
+
+    logging.debug("Generating light xoa logo...")
+    genlogo(os.path.join(gendir, "xoa-logo-light.png"))
+    logging.info("Generated light xoa logo")
+
+    logging.debug("Generating dark xoa logo...")
+    genlogo(os.path.join(gendir, "xoa-logo-dark.png"), dark=True)
+    logging.info("Generated dark xoa logo")
+
+
+def setup(app):
+    app.connect('builder-inited', genlogos)
+    return {'version': '0.1'}
+
+
+if __name__ == "__main__":
+    genlogo("../_static/xoa-logo-light.png")
+    genlogo("../_static/xoa-logo-dark.png", dark=True)

doc/howtostart.rst

@@ -1,13 +1,15 @@
-How to start
-============
+.. _howtostart:
 
+How to get started
+==================
 
-Reading the documentation
+
+Read the documentation
 -------------------------
 
 You should probably start with the :ref:`examples` section.
-This collection of examples will be progressively completed
-to cover almost all the features of the library.
+This collection of examples will gradually be completed
+to cover almost all features of the library.
 
 Some of the modules that are special or of particular interest
 are described in the :ref:`uses` section.
@@ -16,7 +18,7 @@ are described in the :ref:`uses` section.
 Using the library
 -----------------
 
-Like most of all xarray-based projects, xoa not only provides
-a :ref:`library <api>` but also :ref:`accessors <accessors>` for a convenient
-access to part the fonctionalities.
-The two uses are demonstrated in the pratical examples.
+Like most xarray-based projects, xoa provides not only a
+a :ref:`library <api>` but also :ref:`accessors <accessors>` for convenient access to part of the
+access to part of the functionality.
+Both uses are demonstrated in the practical examples.

doc/install.rst

@@ -1,5 +1,7 @@
-Installation
-============
+.. _install:
+
+How to install
+==============
 
 .. highlight:: bash
 
@@ -12,23 +14,22 @@ xoa requires ``python>3`` and depends on the following packages:
    :widths: 10 90
 
    * - `appdirs <http://github.com/ActiveState/appdirs>`_
-     - A small Python module for determining appropriate platform-specific
-       dirs, e.g. a "user data dir".
+     - A small Python module to determine appropriate platform specific dirs, e.g. a "user data dir".
    * - `cmocean <https://matplotlib.org/cmocean>`_
      - Beautiful colormaps for oceanography.
    * - `configobj <https://configobj.readthedocs.io/en/latest/configobj.html>`_
      - ConfigObj is a simple but powerful config file reader and writer:
-       an ini file round tripper.
+       an ini file round-tripper.
    * - `gsw <https://teos-10.github.io/GSW-Python/>`_
      - gsw is the python implementation of the Thermodynamic Equation of
        Seawater 2010 (TEOS-10).
    * - `matplotlib <https://matplotlib.org/>`_
      - Matplotlib is a comprehensive library for creating static, animated,
-       and interactive visualizations in Python.
+       and interactive visualisations in Python.
    * - `numba <https://numba.pydata.org/>`_
      - A high performance python compiler.
    * - `pandas <https://pandas.pydata.org/>`_
-     - pandas is a fast, powerful, flexible and easy to use open source
+     - pandas is a fast, powerful, flexible and easy-to-use open source
        data analysis and manipulation tool, built on top of the
        Python programming language.
    * - `scipy <https://www.scipy.org/scipylib/index.html>`_
@@ -40,7 +41,6 @@ xoa requires ``python>3`` and depends on the following packages:
        with labelled multi-dimensional arrays simple, efficient, and fun!
 
 
-
 From packages
 -------------
 

env/environment.rtd.yml

@@ -23,7 +23,7 @@ dependencies:
       - configobj
       - sphinx
       - sphinx-autosummary-accessors
-      - sphinx_rtd_theme
+      - sphinx-book-theme
       - sphinx-argparse
       - sphinx-gallery
       - sphinxcontrib-programoutput

env/requirements-doc.txt

@@ -14,7 +14,7 @@ scipy
 xarray>=0.17
 sphinx
 sphinx-autosummary-accessors
-sphinx_rtd_theme
+sphinx-book-theme
 sphinx-argparse
 sphinxcontrib-programoutput
 sphinx-gallery

examples/plot_croco_section.py

@@ -25,6 +25,7 @@
 import xoa
 from xoa.regrid import regrid1d
 from xoa.thermdyn import mixed_layer_depth
+import xoa.cf as xcf
 
 xr.set_options(display_style="text")
 
@@ -37,6 +38,17 @@
 # The :ref:`xoa <accessors>` accessor is also registered by default, and give access
 # to most of the fonctionalities of the other accessors.
 
+# %%
+# Register the Mercator and ARGO naming specifications
+
+xcf.register_cf_specs(xoa.get_data_sample("croco.cfg"))
+
+# %%
+# In this way, the :mod:`xoa.cf` module will recognise the
+# CROCO netcdf names.
+# It would be equivalent to force loading name specs with
+# `xoa.cf.set_cf_specs(xoa.get_data_sample("croco.cfg"))`.
+
 # %%
 # Read the model
 # --------------
@@ -82,18 +94,21 @@
 #
 # Let's create the output depths.
 
-depth = xr.DataArray(np.linspace(ds.depth.min(), ds.depth.max(), 1000), name="depth", dims="depth")
+depth = xr.DataArray(
+    np.linspace(ds.depth.values.min(), ds.depth.values.max(), 1000), name="depth", dims="depth"
+)
 
 # %%
 # Let's interpolate the temperature.
 
 tempz = regrid1d(temp, depth, extrap="top")
 
+# %%
 # Compute the mixed layer depths
 # -------------------------------
 #
-# The mixed layer depths are computed here as the depth at wich the temperature
-# is `deltatemp` below the surface temperature,
+# The mixed layer depths are computed here as the depth at which the temperature
+# is `deltatemp` lower than the surface temperature,
 # thanks to the :func:`xoa.thermdyn.mixed_layer_depth` function.
 
 deltatemp = 0.2
@@ -113,6 +128,8 @@
 temp.plot.contour(lat_name, "depth", colors='k', linewidths=0.3, ax=axs[0], **kw)
 tempz.plot.contourf(lat_name, "depth", cmap="cmo.thermal", ax=axs[1], **kw)
 tempz.plot.contour(lat_name, "depth", colors='k', linewidths=0.3, ax=axs[1], **kw)
+axs[0].set_title("Original")
+axs[1].set_title("Interpolated")
 
 # %%
 # Plot a zoom near the surface and add the mixed layer depth isoline.
@@ -126,6 +143,8 @@
 tempz.plot.contour(lat_name, "depth", colors='k', linewidths=0.3, ax=axs[1], **kw)
 mldz.plot.line(x=lat_name, color="k", linewidth=2, linestyle="--", ax=axs[1])
 axs[0].set_ylim(-300, 0)
+axs[0].set_title("Original")
+axs[1].set_title("Interpolated")
 
 # # %%
 # # Et voilà!

examples/plot_hycom_gdp.py

@@ -117,7 +117,7 @@
 # %%
 # Since the sampling is not that nice, we resample it to 3-hour intervals.
 
-drifter = drifter.resample("3H").mean()
+drifter = drifter.resample("3h").mean()
 
 # %%
 # We convert it to and :class:`xarray.Dataset`, fix the time coordinate and decode it.

requirements.txt

@@ -2,7 +2,7 @@ appdirs
 cmocean
 configobj
 numba
-python>=3
+python>=3.10
 setuptools
 scipy
 xarray>=0.17

xoa/cf.cfg

@@ -1,5 +1,5 @@
 [register]
-name=generic
+name=default
 
 [data_vars]