[docs] Fix the docs and document the API

bob/learn/tensorflow/losses/balanced_cross_entropy.py

@@ -28,7 +28,7 @@ def balanced_softmax_cross_entropy_loss_weights(labels, dtype="float32"):
     --------
     >>> import numpy
     >>> import tensorflow as tf
-    >>> from bob.learn.tensorflow.loss import balanced_softmax_cross_entropy_loss_weights
+    >>> from bob.learn.tensorflow.losses import balanced_softmax_cross_entropy_loss_weights
     >>> labels = numpy.array([[1, 0, 0],
     ...                 [1, 0, 0],
     ...                 [0, 0, 1],
@@ -111,13 +111,12 @@ def balanced_sigmoid_cross_entropy_loss_weights(labels, dtype="float32"):
     --------
     >>> import numpy
     >>> import tensorflow as tf
-    >>> from bob.learn.tensorflow.loss import balanced_sigmoid_cross_entropy_loss_weights
+    >>> from bob.learn.tensorflow.losses import balanced_sigmoid_cross_entropy_loss_weights
     >>> labels = numpy.array([1, 1, 0, 0, 0, 1, 1, 0, 1, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, 0, 1, 0,
     ...                 1, 1, 0, 1, 1, 1, 0, 1, 0, 1], dtype="int32")
     >>> sum(labels), len(labels)
     (20, 32)
-    >>> session = tf.Session() # Eager execution is also possible check https://www.tensorflow.org/guide/eager
-    >>> session.run(balanced_sigmoid_cross_entropy_loss_weights(labels, dtype='float32'))
+    >>> balanced_sigmoid_cross_entropy_loss_weights(labels, dtype='float32').numpy()
     array([0.8      , 0.8      , 1.3333334, 1.3333334, 1.3333334, 0.8      ,
            0.8      , 1.3333334, 0.8      , 0.8      , 0.8      , 0.8      ,
            0.8      , 0.8      , 1.3333334, 0.8      , 1.3333334, 0.8      ,

bob/learn/tensorflow/models/__init__.py

 from .alexnet import AlexNet_simplified
+from .densenet import DeepPixBiS
 from .densenet import DenseNet
+from .densenet import densenet161  # noqa: F401
 from .mine import MineModel
 
 
@@ -19,5 +21,5 @@ def __appropriate__(*args):
         obj.__module__ = __name__
 
 
-__appropriate__(AlexNet_simplified, DenseNet, MineModel)
+__appropriate__(AlexNet_simplified, DenseNet, DeepPixBiS, MineModel)
 __all__ = [_ for _ in dir() if not _.startswith("_")]

bob/learn/tensorflow/models/densenet.py

@@ -180,25 +180,35 @@ class TransitionBlock(tf.keras.Model):
 class DenseNet(tf.keras.Model):
     """Creating the Densenet Architecture.
 
-    Arguments:
-        depth_of_model: number of layers in the model.
-        growth_rate: number of filters to add per conv block.
-        num_of_blocks: number of dense blocks.
-        output_classes: number of output classes.
-        num_layers_in_each_block: number of layers in each block.
-                                  If -1, then we calculate this by (depth-3)/4.
-                                  If positive integer, then the it is used as the
-                                    number of layers per block.
-                                  If list or tuple, then this list is used directly.
-        data_format: "channels_first" or "channels_last"
-        bottleneck: boolean, to decide which part of conv block to call.
-        compression: reducing the number of inputs(filters) to the transition block.
-        weight_decay: weight decay
-        rate: dropout rate.
-        pool_initial: If True add a 7x7 conv with stride 2 followed by 3x3 maxpool
-                      else, do a 3x3 conv with stride 1.
-        include_top: If true, GlobalAveragePooling Layer and Dense layer are
-                     included.
+    Parameters
+    ----------
+    depth_of_model
+        number of layers in the model.
+    growth_rate
+        number of filters to add per conv block.
+    num_of_blocks
+        number of dense blocks.
+    output_classes
+        number of output classes.
+    num_layers_in_each_block
+        number of layers in each block. If -1, then we calculate this by
+        (depth-3)/4. If positive integer, then the it is used as the number of
+        layers per block. If list or tuple, then this list is used directly.
+    data_format
+        "channels_first" or "channels_last"
+    bottleneck
+        boolean, to decide which part of conv block to call.
+    compression
+        reducing the number of inputs(filters) to the transition block.
+    weight_decay
+        weight decay
+    rate
+        dropout rate.
+    pool_initial
+        If True add a 7x7 conv with stride 2 followed by 3x3 maxpool else, do a
+        3x3 conv with stride 1.
+    include_top
+        If true, GlobalAveragePooling Layer and Dense layer are included.
     """
 
     def __init__(

bob/learn/tensorflow/utils/math.py

@@ -2,13 +2,13 @@ import tensorflow as tf
 
 
 def gram_matrix(input_tensor):
-    """Computes the gram matrix
+    """Computes the gram matrix.
 
     Parameters
     ----------
-    input_tensor : object
-        The input tensor. Usually it's the activation of a conv layer. The input shape
-        must be ``BHWC``.
+    input_tensor
+        The input tensor. Usually it's the activation of a conv layer. The input
+        shape must be ``BHWC``.
 
     Returns
     -------
@@ -17,15 +17,9 @@ def gram_matrix(input_tensor):
 
     Example
     -------
-    >>>> gram_matrix(tf.zeros((32, 4, 6, 12)))
-    <tf.Tensor: id=53, shape=(32, 12, 12), dtype=float32, numpy=
-    array([[[0., 0., 0., ..., 0., 0., 0.],
-            [0., 0., 0., ..., 0., 0., 0.],
-            [0., 0., 0., ..., 0., 0., 0.],
-            ...,
-            [0., 0., 0., ..., 0., 0., 0.],
-            [0., 0., 0., ..., 0., 0., 0.],
-            [0., 0., 0., ..., 0., 0., 0.]],
+    >>> from bob.learn.tensorflow.utils import gram_matrix
+    >>> gram_matrix(tf.zeros((32, 4, 6, 12))).numpy().shape
+    (32, 12, 12)
     """
     result = tf.linalg.einsum("bijc,bijd->bcd", input_tensor, input_tensor)
     input_shape = tf.shape(input=input_tensor)
@@ -51,13 +45,14 @@ def upper_triangle_and_diagonal(A):
 
     Example
     -------
+    >>> from bob.learn.tensorflow.utils import upper_triangle_and_diagonal
     >>> A = [
     ...  [1, 2, 3],
     ...  [4, 5, 6],
     ...  [7, 8, 9],
     ... ]
-    >>> upper_triangle_and_diagonal(A)
-    [1,2,3,5,6,9]
+    >>> upper_triangle_and_diagonal(A).numpy()
+    array([1, 2, 3, 5, 6, 9], dtype=int32)
     """
     ones = tf.ones_like(A)
     # Upper triangular matrix of 0s and 1s (including diagonal)

doc/nitpick-exceptions.txt

@@ -4,3 +4,4 @@ py:class tensorflow.python.estimator.estimator.Estimator
 py:class tensorflow_estimator.python.estimator.estimator.Estimator
 py:class tensorflow.python.keras.losses.Loss
 py:class tensorflow.python.keras.engine.base_layer.Layer
+py:class tensorflow.python.keras.engine.training.Model

doc/py_api.rst

@@ -10,8 +10,12 @@
 Models
 ======
 
-.. todo:
-  Summary the models
+.. autosummary::
+    bob.learn.tensorflow.models.AlexNet_simplified
+    bob.learn.tensorflow.models.DeepPixBiS
+    bob.learn.tensorflow.models.DenseNet
+    bob.learn.tensorflow.models.densenet161
+    bob.learn.tensorflow.models.MineModel
 
 Data
 ====
@@ -28,13 +32,54 @@ Losses
 .. autosummary::
     bob.learn.tensorflow.losses.CenterLossLayer
     bob.learn.tensorflow.losses.CenterLoss
+    bob.learn.tensorflow.losses.PixelwiseBinaryCrossentropy
+    bob.learn.tensorflow.losses.balanced_sigmoid_cross_entropy_loss_weights
+    bob.learn.tensorflow.losses.balanced_softmax_cross_entropy_loss_weights
+
+
+Image Utilities
+===============
+
+.. autosummary::
+    bob.learn.tensorflow.utils.image.to_channels_last
+    bob.learn.tensorflow.utils.image.to_channels_first
+    bob.learn.tensorflow.utils.image.blocks_tensorflow
+    bob.learn.tensorflow.utils.image.tf_repeat
+    bob.learn.tensorflow.utils.image.all_patches
+
+
+Keras Utilities
+===============
+
+.. autosummary::
+    bob.learn.tensorflow.utils.keras.SequentialLayer
+    bob.learn.tensorflow.utils.keras.keras_channels_index
+    bob.learn.tensorflow.utils.keras.keras_model_weights_as_initializers_for_variables
+    bob.learn.tensorflow.utils.keras.restore_model_variables_from_checkpoint
+    bob.learn.tensorflow.utils.keras.initialize_model_from_checkpoint
+    bob.learn.tensorflow.utils.keras.model_summary
 
 
+Math Utilities
+==============
+
+.. autosummary::
+    bob.learn.tensorflow.utils.math.gram_matrix
+    bob.learn.tensorflow.utils.math.upper_triangle_and_diagonal
+    bob.learn.tensorflow.utils.math.upper_triangle
+    bob.learn.tensorflow.utils.math.pdist
+    bob.learn.tensorflow.utils.math.cdist
+    bob.learn.tensorflow.utils.math.random_choice_no_replacement
+
 
 Detailed Information
 ====================
 
 .. automodule:: bob.learn.tensorflow
 .. automodule:: bob.learn.tensorflow.data
-.. automodule:: bob.learn.tensorflow.utils
 .. automodule:: bob.learn.tensorflow.losses
+.. automodule:: bob.learn.tensorflow.models
+.. automodule:: bob.learn.tensorflow.utils
+.. automodule:: bob.learn.tensorflow.utils.image
+.. automodule:: bob.learn.tensorflow.utils.keras
+.. automodule:: bob.learn.tensorflow.utils.math