Refactor the documentation into more dedicated tutorials

README.rst

@@ -25,7 +25,7 @@ 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-for-doc-index
+.. placeholder-doc-index-start
 
 
 About
@@ -165,6 +165,9 @@ Contacting Us
   ask questions and leave comments.
 
 
+.. placeholder-doc-index-end
+
+
 Citing Pooch
 ------------
 
@@ -226,31 +229,5 @@ License
 -------
 
 This is free software: you can redistribute it and/or modify it under the terms
-of the **BSD 3-clause License**. A copy of this license is provided in
-`LICENSE.txt <https://github.com/fatiando/pooch/blob/master/LICENSE.txt>`__.
-
-
-Documentation for other versions
---------------------------------
-
-* `Development <https://www.fatiando.org/pooch/dev>`__ (reflects the *master* branch on
-  Github)
-* `Latest release <https://www.fatiando.org/pooch/latest>`__
-* `v1.3.0 <https://www.fatiando.org/pooch/v1.3.0>`__
-* `v1.2.0 <https://www.fatiando.org/pooch/v1.2.0>`__
-* `v1.1.1 <https://www.fatiando.org/pooch/v1.1.1>`__
-* `v1.1.0 <https://www.fatiando.org/pooch/v1.1.0>`__
-* `v1.0.0 <https://www.fatiando.org/pooch/v1.0.0>`__
-* `v0.7.1 <https://www.fatiando.org/pooch/v0.7.1>`__
-* `v0.7.0 <https://www.fatiando.org/pooch/v0.7.0>`__
-* `v0.6.0 <https://www.fatiando.org/pooch/v0.6.0>`__
-* `v0.5.2 <https://www.fatiando.org/pooch/v0.5.2>`__
-* `v0.5.1 <https://www.fatiando.org/pooch/v0.5.1>`__
-* `v0.5.0 <https://www.fatiando.org/pooch/v0.5.0>`__
-* `v0.4.0 <https://www.fatiando.org/pooch/v0.4.0>`__
-* `v0.3.1 <https://www.fatiando.org/pooch/v0.3.1>`__
-* `v0.3.0 <https://www.fatiando.org/pooch/v0.3.0>`__
-* `v0.2.1 <https://www.fatiando.org/pooch/v0.2.1>`__
-* `v0.2.0 <https://www.fatiando.org/pooch/v0.2.0>`__
-* `v0.1.1 <https://www.fatiando.org/pooch/v0.1.1>`__
-* `v0.1   <https://www.fatiando.org/pooch/v0.1>`__
+of the `BSD 3-clause License <https://github.com/fatiando/pooch/blob/master/LICENSE.txt>`__.
+A copy of this license is provided with distributions of the software.

doc/api/index.rst

@@ -1,7 +1,7 @@
 .. _api:
 
-API Reference
-=============
+List of functions and classes (API)
+===================================
 
 .. automodule:: pooch
 

doc/authentication.rst

@@ -0,0 +1,82 @@
+.. _authentication:
+
+Authentication
+==============
+
+HTTP authentication
+-------------------
+
+Use the :class:`~pooch.HTTPDownloader` class directly to provide login
+credentials to HTTP servers that require basic authentication. For example:
+
+.. code:: python
+
+    from pooch import HTTPDownloader
+
+
+    def fetch_protected_data():
+        """
+        Fetch a file from a server that requires authentication
+        """
+        # Let the downloader know the login credentials
+        download_auth = HTTPDownloader(auth=("my_username", "my_password"))
+        fname = GOODBOY.fetch("some-data.csv", downloader=download_auth)
+        data = pandas.read_csv(fname)
+        return data
+
+It's probably not a good idea to hard-code credentials in your code. One way
+around this is to ask users to set their own credentials through environment
+variables. The download code could look something like so:
+
+.. code:: python
+
+    import os
+
+
+    def fetch_protected_data():
+        """
+        Fetch a file from a server that requires authentication
+        """
+        # Get the credentials from the user's environment
+        username = os.environ.get("SOMESITE_USERNAME")
+        password = os.environ.get("SOMESITE_PASSWORD")
+        # Let the downloader know the login credentials
+        download_auth = HTTPDownloader(auth=(username, password))
+        fname = GOODBOY.fetch("some-data.csv", downloader=download_auth)
+        data = pandas.read_csv(fname)
+        return data
+
+
+FTP/SFTP with authentication
+----------------------------
+
+Pooch also comes with the :class:`~pooch.FTPDownloader` and
+:class:`~pooch.SFTPDownloader` downloaders that can be used
+when files are distributed over FTP or SFTP (secure FTP).
+
+.. note::
+
+    To download files over SFTP,
+    `paramiko <https://github.com/paramiko/paramiko>`__ needs to be installed.
+
+
+Sometimes the FTP server doesn't support anonymous FTP and needs authentication
+or uses a non-default port.
+In these cases, pass in the downloader class explicitly (works with both FTP
+and SFTP):
+
+.. code:: python
+
+    import os
+
+
+    def fetch_c137():
+        """
+        Load the C-137 sample data as a pandas.DataFrame (over FTP this time).
+        """
+        username = os.environ.get("MYDATASERVER_USERNAME")
+        password = os.environ.get("MYDATASERVER_PASSWORD")
+        download_ftp = pooch.FTPDownloader(username=username, password=password)
+        fname = GOODBOY.fetch("c137.csv", downloader=download_ftp)
+        data = pandas.read_csv(fname)
+        return data