fatiando · leouieda · Jun 8, 2021 · Jun 7, 2021 · Jun 7, 2021 · Jun 7, 2021
diff --git a/README.rst b/README.rst
@@ -25,8 +25,6 @@ Part of the `Fatiando a Terra <https://www.fatiando.org>`__ project
     :alt: Digital Object Identifier for the JOSS paper
     :target: https://doi.org/10.21105/joss.01943
 
-.. placeholder-doc-index-start
-
 
 About
 -----
@@ -165,9 +163,6 @@ Contacting Us
   ask questions and leave comments.
 
 
-.. placeholder-doc-index-end
-
-
 Citing Pooch
 ------------
 

diff --git a/doc/_static/style.css b/doc/_static/style.css
@@ -16,3 +16,15 @@ span.project-version {
 .py-obj {
   margin-right: 0.15rem;
 }
+
+.lead {
+  font-size: 1.5rem;
+}
+
+.front-page-callout {
+  margin-bottom: 4rem;
+}
+
+.text-large {
+  font-size: 1.35rem;
+}
diff --git a/doc/about.rst b/doc/about.rst
@@ -0,0 +1,54 @@
+.. _about:
+
+Why use Pooch?
+==============
+
+Use cases
+---------
+
+
+.. tabbed:: Just download a file
+
+    **Who**: Scientists/researchers/developers looking to simply download a
+    file.
+
+    Pooch makes it easy to download a file (one function call).
+    On top of that, it also comes with some bonus features:
+
+    * Download and cache your data files locally (so it's only downloaded
+      once).
+    * Make sure everyone running the code has the same version of the data
+      files by verifying cryptographic hashes.
+    * Multiple download protocols HTTP/FTP/SFT and basic authentication.
+    * Built-in utilities to unzip/decompress files upon download
+
+    **Start here:** :ref:`retrieve`
+
+.. tabbed:: Use by another library
+
+    **Who**: Package developers wanting to include sample data for use in
+    tutorials and tests.
+
+    Pooch was designed for this! It offers:
+
+    * Pure Python and :ref:`minimal dependencies <dependencies>`.
+    * Download a file only if necessary.
+    * Verification of download integrity through cryptographic hashes.
+    * Extensible design: plug in custom download and post-processing functions.
+    * Built-in utilities to unzip/decompress files upon download
+    * Multiple download protocols HTTP/FTP/SFT and basic authentication.
+    * User control of data cache location through environment variables.
+
+    **Start here:** :ref:`intermediate`
+
+History
+-------
+
+Pooch was born out of shared need between the
+`Fatiando a Terra <https://www.fatiando.org>`__ libraries and
+`MetPy <https://unidata.github.io/MetPy/>`__.
+During the
+`Scipy Conference 2018 <https://www.youtube.com/playlist?list=PLYx7XA2nY5Gd-tNhm79CNMe_qvi35PgUR>`__
+sprints, developers from both projects got together and, realizing the shared
+necessity, devised a package that would combine the best of the existing
+functionality already present in each project and extend it's capabilities.
diff --git a/doc/conf.py b/doc/conf.py
@@ -32,8 +32,16 @@
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
+    "sphinx_panels",
 ]
 
+# Disable including boostrap CSS for sphinx_panels since it's already included
+# with sphinx-book-theme
+panels_add_bootstrap_css = False
+panels_css_variables = {
+    "tabs-color-label-inactive": "hsla(231, 99%, 66%, 0.5)",
+}
+
 # Configuration to include links to other project docs when referencing
 # functions/classes
 intersphinx_mapping = {

diff --git a/doc/index.rst b/doc/index.rst
@@ -8,35 +8,91 @@
     :alt: Pooch Documentation
     :align: middle
 
+.. raw:: html
+
+    <p class="lead centered front-page-callout">
+        Just want to download a file without messing with
+        <code>requests</code> and <code>urllib</code>?
+        <br>
+        Trying to add sample datasets to your Python package?
+        <br>
+        <strong>Pooch is here to help!</strong>
+    </p>
+
+
+.. panels::
+    :header: text-center text-large
+    :card: border-1 m-1 text-center
+
+    **Getting started**
+    ^^^^^^^^^^^^^^^^^^^
+
+    New to Pooch?
+
+    .. link-button:: about
+        :type: ref
+        :text: Start here
+        :classes: btn-outline-primary btn-block stretched-link
+
+    ---
+
+    **Need help?**
+    ^^^^^^^^^^^^^^
+
+    Ask on our chat room
+
+    .. link-button:: http://contact.fatiando.org
+        :type: url
+        :text: Join our Slack
+        :classes: btn-outline-primary btn-block stretched-link
+
+    ---
+
+    **Reference documentation**
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    A list of our functions and classes
+
+    .. link-button:: api
+        :type: ref
+        :text: API reference
+        :classes: btn-outline-primary btn-block stretched-link
+
+    ---
+
+    **Using Pooch for research?**
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Citations help support our work
+
+    .. link-button:: citing
+        :type: ref
+        :text: Cite Pooch
+        :classes: btn-outline-primary btn-block stretched-link
+
+
 .. seealso::
 
     Pooch is a part of the
     `Fatiando a Terra <https://www.fatiando.org/>`_ project.
 
-.. admonition:: Using Pooch for your research?
 
-    Please consider :ref:`citing it <citing>` in your publications.
-    Citations help us get credit for all the effort we put into this project.
-
-
-.. include:: ../README.rst
-    :start-after: placeholder-doc-index-start
-    :end-before: placeholder-doc-index-end
+Table of contents
+-----------------
 
 .. toctree::
-    :maxdepth: 0
-    :hidden:
     :caption: Getting Started
+    :maxdepth: 1
 
+    about.rst
     install.rst
     retrieve.rst
     multiple-files.rst
     sample-data.rst
 
 .. toctree::
-    :maxdepth: 0
-    :hidden:
     :caption: Training your Pooch
+    :maxdepth: 1
 
     hashes.rst
     user-defined-cache.rst
@@ -52,24 +108,21 @@
     decompressing.rst
 
 .. toctree::
-    :maxdepth: 0
-    :hidden:
     :caption: Reference
+    :maxdepth: 1
 
     api/index.rst
-    versions.rst
     compatibility.rst
-    changes.rst
     citing.rst
+    changes.rst
+    versions.rst
 
 .. toctree::
-    :maxdepth: 0
-    :hidden:
-    :caption: Getting help and contributing
+    :caption: Community
 
-    Join the Community <http://contact.fatiando.org>
+    Join the community <http://contact.fatiando.org>
     Code of Conduct <https://github.com/fatiando/pooch/blob/master/CODE_OF_CONDUCT.md>
-    How to Contribute <https://github.com/fatiando/pooch/blob/master/CONTRIBUTING.md>
-    Source Code on GitHub <https://github.com/fatiando/pooch>
+    How to contribute <https://github.com/fatiando/pooch/blob/master/CONTRIBUTING.md>
+    Source code on GitHub <https://github.com/fatiando/pooch>
     Authors <https://github.com/fatiando/pooch/blob/master/AUTHORS.md>
     Fatiando a Terra <https://www.fatiando.org>
diff --git a/doc/install.rst b/doc/install.rst
@@ -23,32 +23,39 @@ doesn't interfere with any other Python installations in your system.
     "Anaconda Prompt" app or ``cmd.exe`` if you're not using Anaconda.
 
 
-Installing with conda
----------------------
+Installing
+----------
+
+There are different ways to install Pooch:
+
+.. tabbed:: conda
+
+    Using the `conda <https://conda.io/>`__ package manager that comes with the
+    Anaconda/Miniconda distribution:
+
+    .. code:: bash
+
+        conda install pooch --channel conda-forge
 
-You can install pooch using the `conda package manager <https://conda.io/>`__
-that comes with the Anaconda distribution::
+.. tabbed:: pip
 
-    conda install pooch --channel conda-forge
+    Using the `pip <https://pypi.org/project/pip/>`__ package manager:
 
+    .. code:: bash
 
-Installing with pip
--------------------
+        python -m pip install pooch
 
-Alternatively, you can also use the `pip package manager
-<https://pypi.org/project/pip/>`__::
 
-    python -m pip install pooch
+.. tabbed:: Development version
 
+    Using ``pip`` to install the latest **unreleased** version from GitHub:
 
-Installing the latest development version
------------------------------------------
+    .. code:: bash
 
-You can use ``pip`` to install the latest version of the source code from
-GitHub::
+        python -m pip install --upgrade git+https://github.com/fatiando/pooch
 
-    python -m pip install --upgrade git+https://github.com/fatiando/pooch
 
+.. _dependencies:
 
 Dependencies
 ------------

diff --git a/doc/sample-data.rst b/doc/sample-data.rst
@@ -5,9 +5,11 @@ Manage a package's sample data
 
 In this section, we'll use Pooch to manage the download of a Python package's
 sample datasets.
-The setup will be very similar to what we saw in :ref:`beginner` (please read
-that tutorial first).
-This time, we'll also use some other features that make our lives a bit easier.
+
+.. note::
+
+    The setup will be very similar to what we saw in :ref:`beginner`.
+    It may be helpful to read that first.
 
 The problem
 -----------
@@ -163,15 +165,15 @@ result in a failed download.
     Requires Pooch >= 1.3.0.
 
 
-
 Where to go from here
 ---------------------
 
 Pooch has more features for handling different download protocols, handling
 large registries, downloading from multiple sources, and more. Check out the
 tutorials under "Training your Pooch" for more information.
 
-You can also customize the download itself (adding authentication, progress
-bars, etc) and apply post-download steps (unzipping an archive, decompressing a
-file, etc) through its :ref:`downloaders <downloaders>` and
-:ref:`processors <processors>`.
+Most users will also benefit from reading at least:
+
+* :ref:`environmentvariable`
+* :ref:`hashes`
+* :ref:`registryfiles`
diff --git a/environment.yml b/environment.yml
@@ -20,3 +20,4 @@ dependencies:
     - pylint==2.4.*
     - sphinx==3.5.*
     - sphinx-book-theme==0.0.41
+    - sphinx-panels==0.5.*
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -6,3 +6,4 @@ pytest-localftpserver
 coverage
 sphinx==3.5.*
 sphinx-book-theme==0.0.41
+sphinx-panels==0.5.*