[doc] Add external docs links and fix wrong refs.

doc/conf.py

@@ -109,4 +109,7 @@ autodoc_default_options = {
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "PIL": ("https://pillow.readthedocs.io/en/latest/", None),
 }

src/bob/io/base/__init__.py

@@ -58,10 +58,8 @@ def create_directories_safe(directory, dryrun=False):
         os.makedirs(directory, exist_ok=True)
 
 
-def open_file(filename):
-    """open_file(filename) -> file.
-
-    Opens a file for reading.
+def open_file(filename) -> np.ndarray:
+    """Reads a file content.
 
     Parameters
     ----------
@@ -118,10 +116,8 @@ def open_file(filename):
         raise ValueError(f"Unknown file extension: {extension}")
 
 
-def write_file(filename, data, format="pillow"):
-    """write_file(filename, data) -> None.
-
-    Writes the contents of a :py:class:`numpy.ndarray` to a file.
+def write_file(filename, data, format="pillow") -> None:
+    """Writes the contents of a :py:class:`numpy.ndarray` to a file.
 
     Parameters
     ----------
@@ -150,11 +146,11 @@ def write_file(filename, data, format="pillow"):
         raise RuntimeError(f"Unknown file extension: {extension}")
 
 
-def load(inputs):
-    """load(inputs) -> data.
+def load(inputs) -> np.ndarray:
+    """Loads the content of a file.
 
-    Loads the contents of a file, an iterable of files, or an iterable of
-    :class:`File` objects into a :py:class:`numpy.ndarray`.
+    Will take a filename (or an iterable of filenames) and put the content into a
+    :py:class:`numpy.ndarray`.
 
     **Parameters:**
 
@@ -169,13 +165,6 @@ def load(inputs):
          would assume that each file contains a single 1D sample or a set of 1D
          samples, load them in memory and concatenate them into a single and
          returned 2D :py:class:`numpy.ndarray`.
-      3. An iterable of :py:class:`File`. In this case, this would assume
-         that each :py:class:`File` contains a single 1D sample or a set
-         of 1D samples, load them in memory if required and concatenate them into
-         a single and returned 2D :py:class:`numpy.ndarray`.
-      4. An iterable with mixed filenames and :py:class:`File`. In this
-         case, this would returned a 2D :py:class:`numpy.ndarray`, as described
-         by points 2 and 3 above.
 
     **Returns:**
 
@@ -208,16 +197,15 @@ def load(inputs):
     else:
         raise TypeError(
             "Unexpected input object. This function is expecting a filename, "
-            "or an iterable of filenames and/or File objects."
+            "or an iterable of filenames."
         )
 
 
 def save(array, filename, create_directories=False):
     """Saves the contents of an array-like object to file.
 
-    Effectively, this is the same as creating a :py:class:`File` object
-    with the mode flag set to ``'w'`` (write with truncation) and calling
-    :py:meth:`File.write` passing ``array`` as parameter.
+    Effectively, this is the same as opening a file with the mode flag set to ``'w'``
+    (write with truncation) and calling ``file.write`` passing ``array`` as parameter.
 
     Parameters:
 

src/bob/io/image.py

@@ -57,7 +57,7 @@ def bob_to_pillow(img):
 
     Returns
     -------
-    Image
+    PIL.Image.Image
         An object of pillow.Image.
     """
     # first convert to matplotlib format
@@ -78,7 +78,7 @@ def pillow_to_bob(img):
 
     Parameters
     ----------
-    img : Image
+    img: PIL.Image.Image
         A Pillow Image
 
     Returns