Refactor dependencies to make more optional

docs/getting-started/installation.rst

@@ -5,42 +5,61 @@
 Installation
 ============
 
-UXarray is built **on top of** `Xarray <https://docs.xarray.dev/en/latest/getting-started-guide/installing.html#installation>`__,
-so we **strongly** recommend becoming familiar with Xarray’s installation
-process and dependencies first.
+UXarray itself is a pure Python package, but its dependencies are not.
+The easiest way to get everything installed is to use conda or pip.
 
-Installing with Conda (recommended)
------------------------------------
+.. admonition:: Conda versus Pip
 
-UXarray itself is a pure Python package, but its dependencies are not.
-The easiest way to get everything installed is to use conda.
-To install UXarray with its recommended dependencies using the conda command line tool:
+    Conda installs UXarray with all optional depencies.
+    Pip installs only the minimal required dependencies by default, but it
+    is also easy to include any/all optional dependencies too, if desired.
 
 
+Installing with Conda
+---------------------
+
+To install UXarray with its recommended dependencies using the conda command line tool:
+
 .. code-block:: bash
 
    conda install -c conda-forge uxarray
 
-.. note::
-
-   Conda automatically installs Xarray and every other required
-   dependency (including non‑Python libraries).
 
 Installing with pip
 -------------------
+For a lightweight installation with **only required dependencies**:
+
 .. code-block:: bash
 
    pip install uxarray
 
-This installs the *minimal* required dependencies. UXarray also provides optional extras:
+
+For a complete installation which also includes **all optional dependencies**:
 
 .. code-block:: bash
 
-   pip install "uxarray[dev]"       # development tools
-   pip install "uxarray[complete]"  # all optional features
+   pip install "uxarray[complete]"
 
-A complete list of extras lives in the ``[project.optional-dependencies]``
-section of our `pyproject.toml <https://github.com/UXARRAY/uxarray/blob/main/pyproject.toml>`_
+
+For an installation including **only some optional dependencies**,
+consider using one of the following extras:
+
+- ``pip install "uxarray[dev]"`` includes development tools (e.g. pytest, ruff)
+- ``pip install "uxarray[geo]"`` includes geospatial packages (e.g. geopandas, healpix)
+- ``pip install "uxarray[viz]"`` includes plotting packages (e.g. matplotlib, hvplot)
+
+It is also possible to combine extras, for example:
+
+- ``pip install "uxarray[geo,viz]"`` includes all geospatial and plotting packages.
+
+
+To see the full lists of which optional dependencies are included with each extra group,
+take a look at the ``[project.optional-dependencies]`` section in ``pyproject.toml``:
+
+.. literalinclude:: ../../pyproject.toml
+   :language: toml
+   :start-at: [project.optional-dependencies]
+   :end-before: [project.urls]
 
 
 Installing from source
@@ -67,9 +86,12 @@ Installing from source is intended mainly for developers.
 
    .. code-block:: bash
 
-      pip install .
+      pip install ".[complete]"   # test suite relies on optional dependencies
+
+#. **Optional: run the test suite**
 
-#. **Run the test suite**
+    Running the test suite is a good way to verify that the installation is working correctly.
+    It should take roughly a minute to run on modern machines.
 
    .. code-block:: bash
 

pyproject.toml

@@ -23,41 +23,52 @@ requires-python = ">=3.10"
 # minimal dependencies start
 dependencies = [
   "antimeridian",
-  "cartopy",
   "dask[dataframe]",
-  "datashader",
-  "geoviews",
-  "holoviews",
-  "matplotlib<3.11",  # matplotlib 3.11.0 breaks some plots but <3.11 is fine; see issue #1542.
-  "matplotlib-inline",
   "netcdf4",
   "numba>=0.63",  # 0.63 is the first release supporting Python 3.14 (3.10 <= py < 3.15). See #1561.
   "numpy",
   "pandas",
-  "pyarrow",
-  "requests",
   "scikit-learn",
   "scipy",
   "shapely",
-  "spatialpandas",
-  "geopandas",
   "xarray",
-  "hvplot",
-  "healpix",
   "polars",
-  "pyproj"
 ]
 # minimal dependencies end
 
 [project.optional-dependencies]
-complete = ["uxarray[dev]"]
-dev = ['pre_commit', 'pytest', 'pytest-cov', 'ruff', 'asv']
+all = ["uxarray[dev,geo,viz]"]
+complete = ["uxarray[dev,geo,viz]"]  # alias to "all"
+dev = [
+    'asv',
+    'pooch',
+    'pre_commit',
+    'pytest',
+    'pytest-cov',
+    'ruff',
+]
+geo = [
+    "cartopy",  # in both geo and viz it is needed by to_geodataframe() and by plotting routines.
+    "geopandas",
+    "healpix",
+    "pyproj",
+    "spatialpandas",
+]
+viz = [
+    "cartopy",
+    "datashader",
+    "matplotlib<3.11",  # matplotlib 3.11.0 breaks some plots but <3.11 is fine; see issue #1542.
+    "geoviews",
+    "holoviews",
+    "hvplot",
+]
 
 [project.urls]
 Documentation = "https://uxarray.readthedocs.io/"
 Source = "https://github.com/UXARRAY/uxarray"
 Tracker = "https://github.com/UXARRAY/uxarray/issues"
-
+# please keep [project.urls] immediately after [project.optional-dependencies],
+# or, if rearranging sections, make sure to edit installation.rst accordingly.
 
 [build-system]
 build-backend = "setuptools.build_meta"

uxarray/plot/accessor.py

@@ -472,6 +472,9 @@ def polygons(
             project=False,
         )
 
+        # import datashader  # no need to import explicitly, but gets used below when rasterize=True.
+        # (commented here for future reference, since datashader appears in uxarray dependency list,
+        #    but it isn't imported explicitly anywhere in uxarray. For more details see PR #1548.)
         return gdf.hvplot.polygons(
             c=self._uxda.name if self._uxda.name is not None else "var",
             rasterize=rasterize,