Refactor the Overview introductory tutorial (#429)

Use data from Ensaio instead of a synthetic. Move some definitions to a
dedicated section. Use more admonitions and explain things in a bit more
detail. Rename to "A taste of Verde".

doc/_static/custom.css

@@ -22,3 +22,9 @@ span.project-version {
   border-top: 1px solid #dddddd;
   padding: 1.8rem 0;
 }
+
+/* Add some margins around jupyter-sphinx outputs */
+.cell_output {
+  margin-top: 1em;
+  margin-bottom: 1em;
+}

doc/_templates/layout.html

@@ -8,7 +8,7 @@
 
 
 {% block htmltitle %}
-    {% if title == '' or title == 'Home' %}
+    {% if title == '' or 'no title' in title %}
         <title>{{ docstitle|striptags|e }}</title>
     {% else %}
         <title>{{ title|striptags|e }} | {{ docstitle|striptags|e }}</title>

doc/changes.rst

@@ -10,10 +10,6 @@ Released on: 2023/05/08
 
 DOI: https://doi.org/10.5281/zenodo.7907182
 
-.. warning::
-
-    **Verde v1.8.0 is the last release that is compatible with Python 3.6.**
-
 Deprecations:
 
 * Deprecate the ``engine`` argument of ``Spline/SplineCV`` (`#373 <https://github.com/fatiando/verde/pull/373>`__)
@@ -74,6 +70,10 @@ Released on: 2022/03/25
 
 DOI: https://doi.org/10.5281/zenodo.6384887
 
+.. warning::
+
+    **Verde v1.7.0 is the last release that is compatible with Python 3.6.**
+
 Deprecation:
 
 * Move the ``CheckerBoard`` class to ``verde.synthetic`` (`#353 <https://github.com/fatiando/verde/pull/353>`__)

doc/conf.py

@@ -31,11 +31,11 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
-    "matplotlib.sphinxext.plot_directive",
     "sphinx.ext.napoleon",
     "sphinx_gallery.gen_gallery",
     "sphinx_design",
     "sphinx_copybutton",
+    "jupyter_sphinx",
 ]
 
 # Configuration to include links to other project docs when referencing

doc/conventions.rst

@@ -0,0 +1,30 @@
+.. _conventions:
+
+Definitions and conventions
+===========================
+
+Here are a few of the conventions and definitions we use across Verde:
+
+.. glossary::
+
+    Coordinate types
+        Coordinates can be **Cartesian or Geographic**. We generally make **no
+        assumptions** about which one you're using.
+
+    Order of coordinates
+        Coordinates are usually given as West-East and South-North. For example,
+        ``longitude, latitude`` or ``easting, northing``. All functions and
+        classes expect coordinates **in this order**. This applies to the
+        actual coordinate values, bounding regions, grid spacing, etc.
+        **Exceptions** to this rule are the ``dims`` and ``shape`` arguments.
+
+    Coordinate names
+        We **don't use names like "x" and "y"** to avoid ambiguity. Cartesian
+        coordinates are "easting" and "northing" and Geographic coordinates are
+        "longitude" and "latitude". Sometimes this doesn't make sense, like
+        when using a polar projection, but we keep the convention for the sake
+        of consistency.
+
+    Region
+        The term "region" means **the bounding box of the data**. It is ordered
+        west, east, south, north.

doc/index.rst

@@ -1,33 +1,28 @@
-.. title:: Home
 
 .. grid::
     :gutter: 4 4 4 4
     :margin: 5 5 0 0
     :padding: 0 0 0 0
 
     .. grid-item::
-        :columns: 12 4 12 4
+        :columns: 12 3 3 3
 
         .. image:: ./_static/verde-logo.svg
             :width: 200px
             :class: sd-m-auto dark-light
 
     .. grid-item::
-        :columns: 12 8 12 8
+        :columns: 12 9 9 9
 
-        .. grid::
-            :padding: 0 0 0 0
+        .. raw:: html
 
-            .. grid-item::
-                :columns: 12 12 12 9
+            <h1 class="display-1"><img class="dark-light" src="_static/verde-title.svg" alt="Verde"></h1>
 
-                .. raw:: html
+.. raw:: html
 
-                    <h1 class="display-1"><img class="dark-light" src="_static/verde-title.svg" alt="Verde"></h1>
-
-        .. div:: sd-fs-3
-
-            Processing and gridding spatial data, machine-learning style
+    <p class="sd-fs-3">
+    Processing and gridding spatial data, machine-learning style.
+    </p>
 
 **Verde** is a Python library for processing spatial data (bathymetry,
 geophysics surveys, etc) and interpolating it on regular grids (i.e.,
@@ -114,8 +109,8 @@ and more!
     :hidden:
     :caption: Getting Started
 
-    tutorials/overview.rst
     install.rst
+    introduction.rst
     gallery/index.rst
 
 .. toctree::
@@ -139,6 +134,7 @@ and more!
     :caption: Reference documentation
 
     api/index.rst
+    conventions.rst
     citing.rst
     references.rst
     changes.rst