From c6edeeafbd75157d4f108bb385f2f6432ca0258b Mon Sep 17 00:00:00 2001
From: Jeremy Kubica <104161096+jeremykubica@users.noreply.github.com>
Date: Thu, 17 Oct 2024 10:04:30 -0400
Subject: [PATCH] Add a getting started page

---
 docs/getting_started.rst | 48 ++++++++++++++++++++++++++++++++++++++++
 docs/index.rst           |  9 ++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 docs/getting_started.rst

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
new file mode 100644
index 00000000..61507ae5
--- /dev/null
+++ b/docs/getting_started.rst
@@ -0,0 +1,48 @@
+Getting Started with HATS
+=========================
+
+Installation
+------------
+
+The latest release version of HATS is available to install with `pip <https://pypi.org/project/hats/>`_ (with conda coming soon).
+
+.. code-block:: bash
+
+    python -m pip install hats
+
+.. hint::
+
+    We recommend using a virtual environment. Before installing the package, create and activate a fresh
+    environment. Here are some examples with different tools:
+
+    .. tab-set::
+
+        .. tab-item:: venv
+
+            .. code-block:: bash
+
+                python -m venv ./hats_env
+                source ./hats_env/bin/activate
+
+        .. tab-item:: pyenv
+
+            With the pyenv-virtualenv plug-in:
+
+            .. code-block:: bash
+
+                pyenv virtualenv 3.11 hats_env
+                pyenv local hats_env
+
+    We recommend Python versions **>=3.9, <=3.12**.
+
+HATS can also be installed from source on `GitHub <https://github.com/astronomy-commons/hats>`_.
+
+
+LSDB
+----
+
+For the most part, we recommend accessing and processing HATS data using the `LSDB package
+<https://github.com/astronomy-commons/lsdb>`_ framework. LSDB provides a variety of utility
+functions as well as a lazy, distributed execution framework using Dask.
+
+For detail on LSDB, see the `readthedocs site <https://docs.lsdb.io/en/stable/>`_.
diff --git a/docs/index.rst b/docs/index.rst
index 72b0d6dc..27b3764a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -27,6 +27,7 @@ operations on top of these utilities. Some known extensions:
    :maxdepth: 1
    :caption: Overview
 
+   getting_started
    guide/directory_scheme
    Notebooks <notebooks>
 
@@ -38,6 +39,14 @@ operations on top of these utilities. Some known extensions:
    Pixel math <guide/pixel_math>
    API Reference <autoapi/index>
 
+Getting Started
+-------------------------------------------------------------------------------
+
+For the most part, we recommend accessing and processing HATS data using the `LSDB package
+<https://github.com/astronomy-commons/lsdb>`_ framework. LSDB provides a variety of utility
+functions as well as a lazy, distributed execution framework using Dask. However if you are are
+interested in using just the HATS package, you can find installation instructions at the :ref:`getting started page<getting_started>`
+
 Acknowledgements
 -------------------------------------------------------------------------------