Update the versions of sphinx and its plugins (#385)

Had to tweak the front page and usage of sphinx-panels (now substituted by sphinx-design). Made sure the front page and README are compatible.
fatiando · Feb 16, 2024 · 11e452c · 11e452c
1 parent abbb2bc
commit 11e452c
Show file tree

Hide file tree

Showing 9 changed files with 152 additions and 129 deletions.
diff --git a/README.md b/README.md
@@ -21,35 +21,24 @@ Part of the <a href="https://www.fatiando.org"><strong>Fatiando a Terra</strong>
 
 ## About
 
-*Does your Python package include sample datasets?
-Are you shipping them with the code?
-Are they getting too big?*
+> Just want to download a file without messing with `requests` and `urllib`?
+> Trying to add sample datasets to your Python package?
+> **Pooch is here to help!**
 
-**Pooch** is here to help! It will manage a data *registry* by downloading your
-data files from a server only when needed and storing them locally in a data
-*cache* (a folder on your computer).
-
-Here are Pooch's main features:
+*Pooch* is a **Python library** that can manage data by **downloading files**
+from a server (only when needed) and storing them locally in a data **cache**
+(a folder on your computer).
 
 * Pure Python and minimal dependencies.
-* Download a file only if necessary (it's not in the data cache or needs to be
-  updated).
-* Verify download integrity through SHA256 hashes (also used to check if a file
-  needs to be updated).
-* Designed to be extended: plug in custom download (FTP, scp, etc) and
-  post-processing (unzip, decompress, rename) functions.
-* Includes utilities to unzip/decompress the data upon download to save loading
-  time.
-* Can handle basic HTTP authentication (for servers that require a login) and
-  printing download progress bars.
-* Easily set up an environment variable to overwrite the data cache location.
-
-*Are you a scientist or researcher? Pooch can help you too!*
-
-* Automatically download your data files so you don't have to keep them in your
-  GitHub repository.
-* Make sure everyone running the code has the same version of the data files
-  (enforced through the SHA256 hashes).
+* Download files over HTTP, FTP, and from data repositories like Zenodo and figshare.
+* Built-in post-processors to unzip/decompress the data after download.
+* Designed to be extended: create custom downloaders and post-processors.
+
+Are you a **scientist** or researcher? Pooch can help you too!
+
+* Host your data on a repository and download using the DOI.
+* Automatically download data using code instead of telling colleagues to do it themselves.
+* Make sure everyone running the code has the same version of the data files.
 
 ## Example
 

diff --git a/doc/_static/favicon.png b/doc/_static/favicon.png
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
@@ -8,7 +8,7 @@
 
 
 {% block htmltitle %}
-    {% if title == '' or title == 'Home' %}
+    {% if title == '' or 'no title' in title or title == 'Home' %}
         <title>{{ docstitle|striptags|e }}</title>
     {% else %}
         <title>{{ title|striptags|e }} | {{ docstitle|striptags|e }}</title>

diff --git a/doc/about.rst b/doc/about.rst
@@ -6,42 +6,43 @@ Why use Pooch?
 Use cases
 ---------
 
+.. tab-set::
 
-.. tabbed:: Just download a file
+    .. tab-item:: Just download a file
 
-    **Who**: Scientists/researchers/developers looking to simply 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:
+        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/SFTP and basic authentication.
-    * Download from Digital Object Identifiers (DOIs) issued by repositories
-      like figshare and Zenodo.
-    * Built-in utilities to unzip/decompress files upon download
+        * 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/SFTP and basic authentication.
+        * Download from Digital Object Identifiers (DOIs) issued by repositories
+          like figshare and Zenodo.
+        * Built-in utilities to unzip/decompress files upon download
 
-    **Start here:** :ref:`retrieve`
+        **Start here:** :ref:`retrieve`
 
-.. tabbed:: Use by another library
+    .. tab-item::  Manage sample data for a Python program
 
-    **Who**: Package developers wanting to include sample data for use in
-    tutorials and tests.
+        **Who**: Package developers wanting to include sample data for use in
+        tutorials and tests.
 
-    Pooch was designed for this! It offers:
+        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/SFTP and basic authentication.
-    * User control of data cache location through environment variables.
+        * 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/SFTP and basic authentication.
+        * User control of data cache location through environment variables.
 
-    **Start here:** :ref:`intermediate`
+        **Start here:** :ref:`intermediate`
 
 History
 -------

diff --git a/doc/conf.py b/doc/conf.py
@@ -32,16 +32,9 @@
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
-    "sphinx_panels",
+    "sphinx_design",
 ]
 
-# 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 = {
@@ -75,7 +68,9 @@
 # -----------------------------------------------------------------------------
 html_title = f'{project} <span class="project-version">{version}</span>'
 html_short_title = project
-html_logo = "_static/pooch-logo.png"
+# Don't use the logo since it gets in the way of the project name and is
+# repeated in the front page.
+# html_logo = "_static/pooch-logo.png"
 html_favicon = "_static/favicon.png"
 html_last_updated_fmt = "%b %d, %Y"
 html_copy_source = True

diff --git a/doc/index.rst b/doc/index.rst
@@ -1,87 +1,114 @@
 .. title:: Home
 
-========
-|banner|
-========
+.. raw:: html
+
+    <div class="text-center">
+    <img src="_static/pooch-logo.svg" class="mx-auto my-4 dark-light" style="width: 100%; max-width: 200px;">
+    <h1 class="display-1">Pooch</h1>
+    <p class="fs-4">
+    <strong>
+    A friend to fetch your data files
+    </strong>
+    </p>
+    </div>
 
-.. |banner| image:: _static/readme-banner.png
-    :alt: Pooch Documentation
-    :align: middle
 
 .. raw:: html
 
-    <p class="lead centered front-page-callout">
+    <p class="fs-5">
         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>
 
+*Pooch* is a **Python library** that can manage data by **downloading files**
+from a server (only when needed) and storing them locally in a data **cache**
+(a folder on your computer).
+
+* Pure Python and minimal dependencies.
+* Download files over HTTP, FTP, and from data repositories like Zenodo and figshare.
+* Built-in post-processors to unzip/decompress the data after download.
+* Designed to be extended: create custom downloaders and post-processors.
 
-.. panels::
-    :header: text-center text-large
-    :card: border-1 m-1 text-center
+Are you a **scientist** or researcher? Pooch can help you too!
 
-    **Getting started**
-    ^^^^^^^^^^^^^^^^^^^
+* Host your data on a repository and download using the DOI.
+* Automatically download data using code instead of telling colleagues to do it themselves.
+* Make sure everyone running the code has the same version of the data files.
 
-    New to Pooch?
+----
 
-    .. link-button:: about
-        :type: ref
-        :text: Start here
-        :classes: btn-outline-primary btn-block stretched-link
+.. grid:: 1 2 1 2
+    :margin: 5 5 0 0
+    :padding: 0 0 0 0
+    :gutter: 4
 
-    ---
+    .. grid-item-card:: :octicon:`info` Getting started
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
 
-    **Need help?**
-    ^^^^^^^^^^^^^^
+        New to Pooch? Start here!
 
-    Ask on our community channels
+        .. button-ref:: about
+            :ref-type: ref
+            :click-parent:
+            :color: primary
+            :outline:
+            :expand:
 
-    .. link-button:: https://www.fatiando.org/contact
-        :type: url
-        :text: Join the conversation
-        :classes: btn-outline-primary btn-block stretched-link
+    .. grid-item-card:: :octicon:`comment-discussion` Need help?
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
 
-    ---
+        Ask on our community channels.
 
-    **Reference documentation**
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        .. button-link:: https://www.fatiando.org/contact
+            :click-parent:
+            :color: primary
+            :outline:
+            :expand:
 
-    A list of our functions and classes
+            Join the conversation :octicon:`link-external`
 
-    .. link-button:: api
-        :type: ref
-        :text: API reference
-        :classes: btn-outline-primary btn-block stretched-link
+    .. grid-item-card:: :octicon:`file-badge` Reference documentation
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
 
-    ---
+        A list of modules and functions.
 
-    **Using Pooch for research?**
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        .. button-ref:: api
+            :ref-type: ref
+            :color: primary
+            :outline:
+            :expand:
 
-    Citations help support our work
+    .. grid-item-card:: :octicon:`bookmark` Using Pooch for research?
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
 
-    .. link-button:: citing
-        :type: ref
-        :text: Cite Pooch
-        :classes: btn-outline-primary btn-block stretched-link
+        Citations help support our work!
 
+        .. button-ref:: citing
+            :ref-type: ref
+            :color: primary
+            :outline:
+            :expand:
+
+----
 
 .. seealso::
 
     Pooch is a part of the
     `Fatiando a Terra <https://www.fatiando.org/>`_ project.
 
-
-Table of contents
------------------
-
 .. toctree::
     :caption: Getting Started
+    :hidden:
     :maxdepth: 1
 
     about.rst
@@ -92,6 +119,7 @@ Table of contents
 
 .. toctree::
     :caption: Training your Pooch
+    :hidden:
     :maxdepth: 1
 
     hashes.rst
@@ -109,6 +137,7 @@ Table of contents
 
 .. toctree::
     :caption: Reference
+    :hidden:
     :maxdepth: 1
 
     api/index.rst
@@ -119,6 +148,7 @@ Table of contents
 
 .. toctree::
     :caption: Community
+    :hidden:
 
     Join the community <https://www.fatiando.org/contact/>
     Code of Conduct <https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md>

diff --git a/doc/install.rst b/doc/install.rst
@@ -5,31 +5,39 @@ Installing
 
 There are different ways to install Pooch:
 
-.. tabbed:: pip
+.. tab-set::
 
-    Using the `pip <https://pypi.org/project/pip/>`__ package manager:
+    .. tab-item:: pip
 
-    .. code:: bash
+        Using the `pip <https://pypi.org/project/pip/>`__ package manager:
 
-        python -m pip install pooch
+        .. code:: bash
 
-.. tabbed:: conda
+            python -m pip install pooch
 
-    Using the `conda <https://conda.io/>`__ package manager that comes with the
-    Anaconda/Miniconda distribution:
+    .. tab-item:: conda/mamba
 
-    .. code:: bash
+        Using the `conda <https://conda.io/>`__ or mamba package manager that
+        comes with the Anaconda/Miniconda/Miniforge distributions:
 
-        conda install pooch --channel conda-forge
+        .. code:: bash
 
-.. tabbed:: Development version
+            conda install pooch --channel conda-forge
 
-    Using ``pip`` to install the latest **unreleased** version from GitHub
-    (**not recommended** in most situations):
+        or
 
-    .. code:: bash
+        .. code:: bash
 
-        python -m pip install --upgrade git+https://github.com/fatiando/pooch
+            mamba install pooch --channel conda-forge
+
+    .. tab-item:: Development version
+
+        Using ``pip`` to install the latest **unreleased** version from GitHub
+        (**not recommended** in most situations):
+
+        .. code:: bash
+
+            python -m pip install --upgrade git+https://github.com/fatiando/pooch
 
 .. note::