diff --git a/README.md b/README.md index 806990a4..b2c53cae 100644 --- a/README.md +++ b/README.md @@ -21,35 +21,24 @@ Part of the Fatiando a Terra ## 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 index d03ecee2..3c960be3 100644 Binary files a/doc/_static/favicon.png and b/doc/_static/favicon.png differ diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index 50fde1fa..0b486cf0 100644 --- 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' %} {{ docstitle|striptags|e }} {% else %} {{ title|striptags|e }} | {{ docstitle|striptags|e }} diff --git a/doc/about.rst b/doc/about.rst index 1969234c..72d37def 100644 --- 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 `. - * 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 `. + * 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 index da2f10b4..6c7bb4de 100644 --- 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} {version}' 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 index 57b98fa5..f2306777 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,87 +1,114 @@ .. title:: Home -======== -|banner| -======== +.. raw:: html + +
+ +

Pooch

+

+ + A friend to fetch your data files + +

+
-.. |banner| image:: _static/readme-banner.png - :alt: Pooch Documentation - :align: middle .. raw:: html -

+

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 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 `_ 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 Code of Conduct diff --git a/doc/install.rst b/doc/install.rst index fb00e1a8..4961ae12 100644 --- 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 `__ package manager: + .. tab-item:: pip - .. code:: bash + Using the `pip `__ package manager: - python -m pip install pooch + .. code:: bash -.. tabbed:: conda + python -m pip install pooch - Using the `conda `__ package manager that comes with the - Anaconda/Miniconda distribution: + .. tab-item:: conda/mamba - .. code:: bash + Using the `conda `__ 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:: diff --git a/env/requirements-docs.txt b/env/requirements-docs.txt index c3099316..adc9427a 100644 --- a/env/requirements-docs.txt +++ b/env/requirements-docs.txt @@ -1,4 +1,4 @@ # Documentation requirements -sphinx==4.4.* -sphinx-book-theme==0.2.* -sphinx-panels==0.6.* +sphinx==7.2.* +sphinx-book-theme==1.1.* +sphinx-design==0.5.* diff --git a/environment.yml b/environment.yml index 0dd03145..0855c00d 100644 --- a/environment.yml +++ b/environment.yml @@ -18,9 +18,9 @@ dependencies: - pytest-httpserver - coverage # Documentation - - sphinx==4.4.* - - sphinx-book-theme==0.2.* - - sphinx-panels==0.6.* + - sphinx==7.2.* + - sphinx-book-theme==1.1.* + - sphinx-design==0.5.* # Style - pathspec - black>=20.8b1