From d6b18cee3e2199265e6ae53892d0aa19b7c06de9 Mon Sep 17 00:00:00 2001 From: Leonardo Uieda Date: Fri, 16 Feb 2024 14:29:11 -0300 Subject: [PATCH] Update the versions of sphinx and its plugins 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. --- README.md | 41 +++++------- doc/_static/favicon.png | Bin 1700 -> 5262 bytes doc/_templates/layout.html | 2 +- doc/about.rst | 53 ++++++++-------- doc/conf.py | 13 ++-- doc/index.rst | 124 +++++++++++++++++++++++-------------- doc/install.rst | 36 ++++++----- env/requirements-docs.txt | 6 +- environment.yml | 6 +- 9 files changed, 152 insertions(+), 129 deletions(-) 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 d03ecee2f9f6ee876437ff44169c60c77525ac94..3c960be3f247a1255151e94436127dc961cb68f2 100644 GIT binary patch literal 5262 zcmeHKc~lcu7oPwTMFWUXmtu)gR8m70vO^F}K!QY4L?nWhNiqooWHAX4Fx4Px#f4T8 z0SgFK!B!O4sw@(#Sha$v;DS|BXjO^}pVFcN+DSmf^YxtXc+S`VOwMHH-S@k{ckl1s z_f95LxL_W}VUhy?02qESFC4jJE!W5q$gegntsA-3rA0*P!od`*TBDM|i4azos)n$T z9+m-szC|ItjX6Ua*(cwSWkmVv-LIC0GafvzTgT(y&c4*yIMMj1KkY|_af7ibFj|F~ ze05KDYVm}F@aT(2$8FnoKbP%pmzsG;ySwG^s)}4LwjebkY;IbZxW;8^__EqHPp5t| zZnM`XUQG+vd#&GU^HBoWSy`|+icvkc{WK}z`-aReMs8h2&)!!~;}kIy?oj5BF}066 zSZ^v&-i@k0eWGDQ*Qu=@zqJ-7o9vlX(fOFr)oTC%wFc&Lg?ujeO+rW-1z&981fL0* zu&%Xq1I`WYyMDcN?}FqjxU6FifqR|f*G5hb_3qD@j^S_ExXZjm-6cQthqkw`(TU9Ypig$u499UB>l`E5c{!n*nL+NK(F&igE&mCBpU|*m&$%T%zY)j$ z{$~z!;M$}>myJ=Y?Z!I9&)jA6@nYY~@zZ*-Ui&gcV(VgyPP66xEaw<`dj_H{=sG_&J>i7}W z>+45f_Sn|SHFcw$wZ9>ar-zXSixPygB`SqCC{>9eZ@of|bRGcs&DN_yNdlz9iXl0y z=LeB@kk{Dh-6CdQ-hggg`xjQUY115OQxA;gOK2bcjZQ z2ok20PN0$)Oae$^(g_rak61zhX=E0KIgBDq10!7tCJv9vLM270WKgiBPE$IXFuISc~V-v;f&oQcwr-KpljTk|-d^;4~;fgQCFT0Sru7$(Bj zt%Su|Hw7D%45Xk1lc9lnBU}Shk~mN)hmg}_uwCES;eTocsRWYBATmM9WFYlp`j81? zmQ+k&F{D%}g9XZ@5{6ZUA$F}wrb_`e&>T6UBcc`3o>r}}Gp&X4dKaA%2U)6s2u2`L z2yX>LhE~Cdg9#HYXU3b1{fPgiiJuiP?2tkH25iXTg`9=Np~G-cGbG-B^D|hBe{%^e z_QN9YrSAv1KFIZ63cMHiLw9|U>%A0sFYt%%`oGEL@b+~IQX>C?QjnLWzj8+6kr%BI z;`#Gm)LEGgqniN0j?U-J ziHJH=lbaA16X^QWs_cjBPGs(<{Q$c}?g@G+q%WPtgTFQj;y(@F6crL7ED@vKb}u^k z12bsa$}Q_Rlx{iea>eO%_mq#0Rtk86exdf!%Q$?(>GFh@rW32{chyV!%>2R_#)ZeF zdjI-@{1va{4F%6?<*uUOsCnB_Rq4$p$$@0C)C8q%|5xn$W zLHP$%J1fW{U+3#vJWUJC{9@9^j8`^P{3_-AC)#Eo_Y3@MCdb&t+s(iYRK3h_*tdLY z-LoKU`BXO(*EE3yFirPZz$u#+kjskhuoSIpM}a$-6~SX2R!^_|dfisLNw%XGtw z@+Aa7{T&c_anUJ^d#+vgMGoF|Hg&+2Os07Z>#o56`N`PpzpnJY`guvs+f&iWnV8zpJb+i_3+7C zlbl5D3EFVretz6RLA+ZrE+e|q=B87%!^0!p3{g``!}K5BiA?o*d`>HB)w&m=F*+0` zpz47`DD}Bh>cs8QE6NOBb5C5^@s-Fk+pEXJ4gZNvk;@%X@uilOi}J$HZJqRE`q6er z%9}dVdlt<+b(fd1%r@}bio<{P#mnw)=&*60dDt`_CAi+=dmwr1T}t9uM|&nZ{!fED z+Th^#cuF4ppV22go(H&$HHQVfE}I%&@*HhO=dWy^;#{G#sl&Ur0uRxVr8lpQzrMw& z=I-CKs;Rl*q-Y7{nnQt|zpZ14eRjwn#$Lz}{k>+g->MZZ4^WQ}H&vWy>Bu`aBcfzk z*_t4yeL@2-M2lZ*%L>TO91+batD4r^OK(ccJ9?|Rp%cpQcfthjdpO?%e8D3N^_ z^X$n>@5R2vGIk*Q@|WX1Z(U7WHfD3gRdxBwN!1>E`RJn0!s5O?ZRjv`)+AiG68(Vv zg*}k@>)gA7Z6vTMPdz_lU*WSOx9SBq(w#OsZF|H??TI@iI`(*n>G`7cYP<2%FEWd6 zUd$?Dr)AHdNt^&KezQP8dJCDZS-=sh`(rC$2FUJ>ql0KiNs?~I? z45_}M6mEMl`bD+276s)8 W8FtU;nvNVQ06%a6@4(#H)qexB4CX!n delta 1684 zcmV;F25b3_DWnaMB!2{RLP=Bz2nYy#2xN!=000SaNLh0L00c|`00c|{J#|oZ0000P zbVXQnQ*UN;cVTj60C#tHE@^ISb7Ns}WiD@WXPfRk8UO$WAxT6*R9J=Wms@O9#~p{i zIcIOS*WSguzF)9iXfY5&5tLpc8lVD_DuI%kN+~r2sYy}VN`DoqstBpF(yCF@K2=fF zCTfdlKn*;QhJ>`i3Xp^XPAag24Hy$&)?R#DZ0y~&&vp9Xu=d)!wo!TP?`{5<`F%4x zXZ9Sy15#DpN9C5V&kG@YKy+nfj5RE)IeGEK{y$!wt4};AfQr3mDnRX+9$T{Fw4GPn z+C4s6^z@tiUw=NEs!w@P05j!qP7o})rZ`+$g(d8Uoqyi*ZtbyJb!Odt?Z6YSJhvw@ zu;k(X(Aw%}ww0_5<~Y4gfB2Dwl>MWQK;N0%AFi8TUs-*IyrS#e8LT2c7NDrC>6$TA zu>P%Iyfl^oU5N44-|jo$FY2j}$EDZf$l~bFSFpOu%YWbA?_*zCnHsmOvJTTzc1BM1 z6qH`2dd*t^1dG}*^bC4F`%3kgmVctYo-OtD*z*Ex{!LxLy0&kb?dZo$vp?m5t9|W;kl3h1Vv$DdR48l>FlBTX+2FnJsAn z9(!qT;Ua(YMSWb!xct!`bR#dVQ96aYzKktXuTLlznK_Zy(gNtZ`F_i#M>Cr*eGk*{ zARO+rMozDWQ0-aq=-onE8h2rt&Xj$=V0ZZwuYc^XnRN!X{jRRQzcW}p9t$9)_?$TP zBmhhIeu6X=lp7UrDmfQwUr)GmH7<7yDHT?I?FfOw_Q^T1ab#%E&)5MeEF=1pU{N~` zr-l%cOm75FW-KiLfN$_*B_ zk$;nJ)aeAg$rLA&zxRjQUpXACxCx1u_bL2h3{auNgcsPe}!_p*xAzkM^W8g;j zx{7B3Yz;m65DHO>oV?Dmef`r6WpbHf;SY3CTGa@A1B8mhzm;!}8;(yGZ zNa}Gb3JxK1_dfE7=Uyza13s6o#PzA-f$(w)%3AQ{hOklqj0}}A5%;tGSAB^;7Q@`k zgs~}69M#>@vQ<`YdDZLjM-+gu;R5U2-w!BoHW{G($nMeN?T2DO7J#%Jv@|}+msY(? zf$L_HxwKWnoofMT9xlwDMK?{Vs(+Ie3?sxOS9G+*3ZHyDelMT&6bQua>0`@s(bKUO zQ@63L&le^Iml~cUbZh-wz6mJ~BVi8E)3K%}DW9}5Rh(mn;?V#Addvc#uje7|3|214 z96&H--WRH2WZ(<`NDJT)j-(`jX?W1bbI_s|mg%Ie>9GZy1NieMAI*u_B7a&Mzl%hi zObgH*82hIX%4ahtiH_!BYBtU1cM!c>a9;q1mPPl?uXEw_kI^QwTRUU7KTHe2tIry? zP=7gdlHs9Bq*MsqsJbt6fZ@Rkt~S;(9?J!+gB;&wr3V0RpLpu15X#x^{D))z;)X5FgCU zZTO;sG@|ob3*^6SeeA30%qMH+l@ul4Ir;-B%@>ezaZRO{r@vK5Z+}FmWzb7@wwLmt zhti-2UzSQ}P~+EcbarCP`p&}}4uhEU_ge6W$%@)zt`TW$Kd__f;OYw3%0*d{{ 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