DOC: Add pyart 2.0 migration guide (#1625)

* DOC: Add pyart 2.0 migration guide

* ADD: Add revised structure to py-art 2.0

doc/source/conf.py

@@ -97,7 +97,7 @@
 
 # General information about the project.
 project = "Py-ART"
-copyright = "2013-2022, Py-ART developers"
+copyright = "2013-2024, Py-ART developers"
 author = "Py-ART developers"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -106,19 +106,16 @@
 #
 import pyart
 
-# The short X.Y version (including the .devXXXX suffix if present)
-version = re.sub(r"^(\d+\.\d+)\.\d+(.*)", r"\1\2", pyart.__version__)
-if "dev" in version:
-    # retain the .dev suffix, but clean it up
-    version = re.sub(r"(\.dev\d*).*?$", r"\1", version)
-else:
-    # strip all other suffixes
-    version = re.sub(r"^(\d+\.\d+).*?$", r"\1", version)
+verinfo = pyart.__version__
+parsed_version = re.search(r"(?P<full>(?P<base>\d+\.\d+)\.?\w*)", verinfo).groupdict()
+
+# The short X.Y version.
+version = parsed_version["base"]
+if "+" in verinfo:
+    version += "dev"
 # The full version, including alpha/beta/rc tags.
-release = pyart.__version__
-# full Py-ART version in CI built docs
-if "CI" in os.environ and os.environ["CI"] == "true":
-    version = release
+release = parsed_version["full"]
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -151,6 +148,9 @@
 # documentation.
 #
 html_theme_options = {
+    "external_links": [
+        {"name": "Release Notes", "url": "https://github.com/ARM-DOE/pyart/releases"},
+    ],
     "analytics": {"google_analytics_id": "G-JJEG3CV376"},
     "github_url": "https://github.com/ARM-DOE/pyart",
     "twitter_url": "https://twitter.com/Py_ART",

doc/source/index.rst

@@ -30,13 +30,6 @@ The Python ARM Radar Toolkit - Py-ART
 
    dev/index.rst
 
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: Notebook Gallery
-
-   notebook-gallery.rst
-
 .. toctree::
    :maxdepth: 1
    :hidden:
@@ -45,11 +38,11 @@ The Python ARM Radar Toolkit - Py-ART
    blog.md
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :hidden:
-   :caption: Changelog
+   :caption: Notebook Gallery
 
-   changelog.md
+   notebook-gallery.rst
 
 .. grid:: 1 2 2 2
     :gutter: 2

doc/source/userguide/index.rst

@@ -9,6 +9,7 @@ We also have a collection of installation, and contribution instructions listed
 .. toctree::
    :maxdepth: 1
 
+   pyart_2_0
    INSTALL
    setting_up_an_environment
    contributors_guide

doc/source/userguide/pyart_2_0.rst

@@ -0,0 +1,60 @@
+==========
+Py-ART 2.0
+==========
+
+In preparation for version 2.0.0 of Py-ART, codes were standardized for consistency purposes as further defined in the `Contributor's Guide <https://arm-doe.github.io/pyart/userguide/CONTRIBUTING.html>`_.  These changes will break some users code as the API has changed.  This guide will detail the changes for each module.
+
+How to Try Py-ART 2.0
+=====================
+
+The Py-ART 2.0 release candidate can be installed directly from github - this is still a work in progress, feedback is welcome!::
+
+    pip install git+https://github.com/ARM-DOE/pyart@release/2.0
+
+Input/Output (IO)
+=================
+We now offer the option to use xradar for IO, with the following interface (a typical gridding workflow is shown below):
+
+.. code-block:: python
+
+    import xradar as xd
+    import pyart
+
+    # Access sample cfradial1 data from Py-ART and read using xradar
+    filename = get_test_data("swx_20120520_0641.nc")
+    tree = xd.io.open_cfradial1_datatree(filename)
+
+    # Add the associated pyart methods - ensuring compatibility with Py-ART functionality
+    radar = tree.pyart.to_radar()
+
+    # Grid using 11 vertical levels, and 101 horizontal grid cells at a resolution on 1 km
+    grid = pyart.map.grid_from_radars(
+        (radar,),
+        grid_shape=(11, 101, 101),
+        grid_limits=(
+            (0.0, 10_000),
+            (-50_000.0, 50_000.0),
+            (-50_000, 50_000.0),
+        ),
+    )
+
+Correct
+=======
+The `dealias_fourdd <https://arm-doe.github.io/pyart/API/generated/pyart.correct.dealias_fourdd.html>`_ algorithm has been removed given the now unsupported RSL library.
+
+It is recommended that users move to the `region-based dealiasing algorithm <https://arm-doe.github.io/pyart/API/generated/pyart.correct.dealias_region_based.html>`_.
+
+Graph
+=====
+Colormaps have been moved to a dedicated package outside Py-ART, `cmweather <https://cmweather.readthedocs.io/>`_.
+
+For example, visualizing our grid mentioned previously, it is recommended to install/import cmweather and change the colormap name from `pyart_ChaseSpectral` to `ChaseSpectral`
+
+.. code-block:: python
+
+    import cmweather
+
+    display = pyart.graph.GridMapDisplay(grid)
+    display.plot_grid(
+        "reflectivity_horizontal", level=0, vmin=-20, vmax=60, cmap="ChaseSpectral"
+    )