From 722a85fe6ffaf036c431812866e439a8c4e39190 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 9 Dec 2025 20:54:15 +0000
Subject: [PATCH] docs: reorganize introduction and index page

The previous index page was mostly empty and not very helpful for new users. This commit reorganizes the documentation to provide a better onboarding experience.

Key changes:
- Merged the content of `installation.rst` into `index.rst`.
- Moved a core usage example from `how_to_use.rst` to `index.rst`.
- Deleted the now-redundant `installation.rst` file.
- Updated the `toctree` in `index.rst` to reflect the new structure.

This makes the main landing page a more useful quickstart guide, immediately presenting the package's purpose, how to install it, and a simple example of how to use it.
---
 docs/index.rst        | 42 +++++++++++++++++++++++++++++++++++++++++-
 docs/installation.rst | 27 ---------------------------
 2 files changed, 41 insertions(+), 28 deletions(-)
 delete mode 100644 docs/installation.rst

diff --git a/docs/index.rst b/docs/index.rst
index c7e0406..1b3d717 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,11 +7,51 @@ Welcome to mapflow's documentation!
 
 ``mapflow`` transforms 3D ``xr.DataArray`` into video files in one line of code.
 
+Installation
+------------
+
+You can install ``mapflow`` using ``pip`` or ``conda``.
+
+With pip
+~~~~~~~~
+
+.. code-block:: bash
+
+   pip install mapflow
+
+With conda
+~~~~~~~~~~
+
+.. code-block:: bash
+
+   conda install -c conda-forge -y mapflow
+
+Dependencies
+~~~~~~~~~~~~
+
+``mapflow`` relies on ``matplotlib`` and ``ffmpeg``. If you're not installing ``mapflow`` from conda-forge, make sure ``ffmpeg`` is installed on your system.
+
+Usage
+-----
+
+The main function of ``mapflow`` is ``animate``, which creates a video from an ``xarray.DataArray``.
+
+.. code-block:: python
+
+   import xarray as xr
+   from mapflow import animate
+
+   ds = xr.tutorial.open_dataset("era5-2mt-2019-03-uk.grib")
+   animate(da=ds['t2m'].isel(time=slice(120)), path='animation.mp4')
+
+.. video:: ../_static/animation.mp4
+   :width: 640
+   :height: 480
+
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
    :hidden:
 
-   installation
    how_to_use
    api
diff --git a/docs/installation.rst b/docs/installation.rst
deleted file mode 100644
index 179671e..0000000
--- a/docs/installation.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-:notoc: true
-
-.. _installation:
-
-Installation
-============
-
-You can install ``mapflow`` using ``pip`` or ``conda``.
-
-With pip
---------
-
-.. code-block:: bash
-
-   pip install mapflow
-
-With conda
-----------
-
-.. code-block:: bash
-
-   conda install -c conda-forge -y mapflow
-
-Dependencies
-------------
-
-``mapflow`` relies on ``matplotlib`` and ``ffmpeg``. If you're not installing ``mapflow`` from conda-forge, make sure ``ffmpeg`` is installed on your system.