update Why UXarray and Install sections

Author: philipc2

docs/getting-started/installation.rst

@@ -1,116 +1,92 @@
 .. currentmodule:: uxarray
-
 .. _installation:
 
+================
 Installation
-============
+================
 
-This installation guide includes only the UXarray installation instructions. Please
-refer to `UXarray Contributor's Guide <https://uxarray.readthedocs.io/en/latest/contributing.html>`_
-for detailed information about how to contribute to the UXarray project.
+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.
 
-Installing UXarray via Conda
-----------------------------
+For details on contributing, see the :doc:`UXarray Contributor’s Guide <contributing>`.
 
-The easiest way to install UXarray along with its dependencies is via
-`Conda <https://conda.io/en/latest>`_::
 
-    conda install -c conda-forge uxarray
+Installing with Conda (recommended)
+-----------------------------------
 
-Note that the Conda package manager automatically installs all `required`
-dependencies of UXarray, meaning it is not necessary to explicitly install
-Xarray or other required packages when installing UXarray.
+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:
 
-If you are interested in learning more about how Conda environments work, please
-visit the `managing environments <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_
-page of the Conda documentation.
 
-Installing UXarray via PyPI
----------------------------
+.. code-block:: bash
 
-An alternative to Conda is using pip::
+   conda install -c conda-forge uxarray
 
-    pip install uxarray
+.. note::
 
-This installs the minimum set of required dependencies, which includes the following:
+   Conda automatically installs Xarray and every other required
+   dependency (including non‑Python libraries).
 
-.. literalinclude:: ../pyproject.toml
-   :language: toml
-   :start-after: minimal dependencies start
-   :end-before: minimal dependencies end
+Installing with pip
+-------------------
+.. code-block:: bash
 
+   pip install uxarray
 
-UXarray also maintains other dependency sets for different subsets of functionality::
+This installs the *minimal* required dependencies. UXarray also provides optional extras:
 
-    $ python -m pip install "uxarray[math]"       # Install optional dependencies for accurate math utlities
-    $ python -m pip install "uxarray[dev]"        # Install optional dependencies for development
-    $ python -m pip install "uxarray[complete]"   # Install all optional dependencies
+.. code-block:: bash
 
-The above commands should install most of the optional dependencies. However,
-some packages which are either not listed on PyPI or require extra
-installation steps are excluded. To know which dependencies would be
-installed, take a look at the ``[project.optional-dependencies]`` section in
-``pyproject.toml``:
+   pip install "uxarray[dev]"       # development tools
+   pip install "uxarray[complete]"  # all optional features
 
-.. literalinclude:: ../pyproject.toml
-   :language: toml
-   :start-at: [project.optional-dependencies]
-   :end-before: [project.urls]
+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>`_
 
-Installing UXarray from source (Github)
----------------------------------------
 
-Installing UXarray from source code is a fairly straightforward task, but
-doing so should not be necessary for most users. If you `are` interested in
-installing UXarray from source, you will first need to get the latest version
-of the code::
+Installing from source
+----------------------
+Installing from source is intended mainly for developers.
 
-    git clone https://github.com/UXARRAY/uxarray.git
-    cd uxarray
+#. **Clone the repo**
 
-Required dependencies for installing and testing UXarray
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   .. code-block:: bash
 
-The following packages should be installed (in your active conda
-environment)::
+      git clone https://github.com/UXARRAY/uxarray.git
+      cd uxarray
 
-    - Python 3.9+
-    - `pytest <https://docs.pytest.org/en/stable/>`_  (For tests only)
-    - `xarray <http://xarray.pydata.org/en/stable/>`_
+#. **Create a dev environment**
 
-If you don't have these packages installed, the next section describes
-how to setup a conda environment with them.
+A ready‑made file is provided at ``ci/environment.yml``:
 
-Creating a Conda environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   .. code-block:: bash
 
-The UXarray source code includes a conda environment definition file
-(:code:`environment.yml`) in the :code:`/ci` folder under the root
-directory that can be used to create a development environment
-containing all of the packages required to build UXarray. The
-following commands should work on Windows, Linux, and macOS to create
-and activate a new conda environment from that file::
+      conda env create -f ci/environment.yml
+      conda activate uxarray_build
 
-    conda env create -f ci/environment.yml
-    conda activate uxarray_build
+#. **Install UXarray**
 
-Installing from source
-^^^^^^^^^^^^^^^^^^^^^^
+   .. code-block:: bash
+
+      pip install .
 
-Once the dependencies listed above are installed, you can install
-UXarray with running the following command from the root-directory::
+#. **Run the test‑suite**
+
+   .. code-block:: bash
+
+      pytest test
+
+Verifying your installation
+---------------------------
 
-    pip install .
+After installing UXarray, you can verify the installation by running the following in a Python shell or script:
 
-For compatibility purposes, we strongly recommend using Conda to
-configure your build environment as described above.
+.. code-block:: python
 
-Testing UXarray source
-^^^^^^^^^^^^^^^^^^^^^^
+    import uxarray as ux
 
-A UXarray code base can be tested from the root directory of the source
-code repository using the following command (Explicit installation of the
-`pytest <https://docs.pytest.org/en/stable/>`_ package may be required, please
-see above)::
+    print(ux.__version__)
 
-    pytest test
+This should print the installed version of UXarray without errors.

docs/getting-started/overview.rst

@@ -8,7 +8,7 @@ data analysis techniques to operate directly on unstructured grids. It extends u
 and inherits from the commonly used Xarray Python package to provide a powerful and
 familiar interface for working with unstructured grids in Python. UXarray provides
 Xarray styled functions to better read in and use unstructured grid datasets that
-follow standard conventions, including UGRID, MPAS, SCRIP, and Exodus formats.
+follow standard conventions, including UGRID, MPAS, SCRIP, ICON, HEALPix, and Exodus formats.
 
 
 Unstructured Grids
@@ -27,7 +27,7 @@ single convention for our grid representation instead of having separate ones fo
 grid format, meaning that we encode all supported unstructured grid formats in the
 UGRID conventions at the data loading step.
 
-Specifically, our core functionality is build around two-dimension
+Specifically, our core functionality is built around two-dimensional
 Unstructured Grids as defined by the 2D Flexible Mesh Topology in the
 UGRID conventions, which can contain a mix of triangles, quadrilaterals, or
 other geometric faces.
@@ -36,30 +36,38 @@ other geometric faces.
 Core Data Structures
 ====================
 
-The functionality of UXarray is built around three core data structures which provide
-an Unstructured Grid aware implementation of many Xarray functions and use cases.
+UXarray’s core API revolves around three primary types, which extend Xarray for unstructured-grid workflows:
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 0
+
+   * - :py:class:`uxarray.Grid`
+     - Represents the unstructured grid itself, housing grid-specific methods and topology variables. Encapsulates a :py:class:`xarray.Dataset` for storing the grid definition.
+
+   * - :py:class:`uxarray.UxDataset`
+     - Extends :py:class:`xarray.Dataset` to operate on unstructured grids; linked to a :py:class:`~uxarray.Grid` instance via its ``uxgrid`` property.
+
+   * - :py:class:`uxarray.UxDataArray`
+     - Similarly extends :py:class:`xarray.DataArray` and exposes a ``uxgrid`` accessor for grid-aware operations.
+
 
-* ``Grid`` is used to represent our Unstructured Grid, housing grid-specific methods
-  and topology variables.
-* ``UxDataset`` inherits from the ``xarray.Dataset`` class, providing much of the same
-  functionality but extended to operate on Unstructured Grids. Other than new and
-  overloaded methods, it is linked to a ``Grid`` object through the use of a class
-  property (``UxDataset.uxgrid``) to provide a grid-aware implementation. An instance
-  of ``UxDataset`` can be thought of as a collection of Data Variables that reside on
-  some Unstructured Grid as defined in the ``uxgrid`` property.
-* ``UxDataArray`` similarly inherits from the ``xarray.DataArray`` class and contains
-  a ``Grid`` property (``UxDataArray.uxgrid``) just like ``UxDataset``.
 
 Core Functionality
 ==================
 
-In addition to providing a way to load in and interface with Unstructured Grids, we
-also aim to provide computational and analysis operators that directly operate on
-Unstructured Grids. Some of these include:
+In addition to loading and interfacing with Unstructured Grids, UXarray provides
+computational and analysis operators that operate directly on those grids. Some of
+these include:
+
 * Visualization
 * Remapping
-* Subsetting & Selection
+* Subsetting
+* Cross-Sections
 * Aggregations
+* Zonal Averaging
 
-A more detailed overview of supported functionality can be found in our `API Reference <https://uxarray.readthedocs.io/en/latest/api.html>`_
-and `User Guide <https://uxarray.readthedocs.io/en/latest/userguide.html>`_ sections.
+A more detailed overview of supported functionality can be found in our
+`API Reference <https://uxarray.readthedocs.io/en/latest/api.html>`_
+and `User Guide <https://uxarray.readthedocs.io/en/latest/userguide.html>`_
+sections.