Callbacks: improve doc

ashpy/callbacks/__init__.py

@@ -15,6 +15,36 @@
 """
 Callbacks in order to gain control over the training loop.
 
+A callback is a set of functions to be called at given stages of the training procedure.
+You can use callbacks to implement logging, measure custom metrics or get insight about the
+training procedure.
+You can pass a list of callbacks (derived from :py:class:`ashpy.callbacks.callback.Callback`)
+(as the keyword argument callbacks)
+to the `.call()` method of the Trainer.
+The relevant methods of the callbacks will then be called at each stage of the training.
+
+Order:
+    .. code-block::
+
+        --on_train_start
+
+        ----on_epoch_start
+
+        ------on_batch_start
+
+        ------on_batch_end
+
+        ----on_epoch_end
+
+        --on_train_end
+
+        on_exception – if an Exception was raised
+
+        on_event - Called when an event is triggered
+
+The basic class is :py:class:`ashpy.callbacks.callback.Callback` .
+All possible events as listed as Enum inside :py:class:`ashpy.callbacks.events.Event` .
+
 .. currentmodule:: ashpy.callbacks
 
 .. rubric:: Classes

ashpy/callbacks/events.py

@@ -20,10 +20,10 @@
 class Event(Enum):
     """Define all possible events."""
 
-    ON_BATCH_START = "ON_BATCH_START"
-    ON_BATCH_END = "ON_BATCH_END"
-    ON_TRAIN_START = "ON_TRAIN_START"
-    ON_TRAIN_END = "ON_TRAIN_END"
-    ON_EPOCH_START = "ON_EPOCH_START"
-    ON_EPOCH_END = "ON_EPOCH_END"
-    ON_EXCEPTION = "ON_EXCEPTION"
+    ON_BATCH_START = "ON_BATCH_START"  #: On Batch Start Event
+    ON_BATCH_END = "ON_BATCH_END"  #: On Batch End Event
+    ON_TRAIN_START = "ON_TRAIN_START"  #: On Train Start Event
+    ON_TRAIN_END = "ON_TRAIN_END"  #: On Train End Event
+    ON_EPOCH_START = "ON_EPOCH_START"  #: On Epoch Start Event
+    ON_EPOCH_END = "ON_EPOCH_END"  #: On Epoch End Event
+    ON_EXCEPTION = "ON_EXCEPTION"  #: On Exception Event

ashpy/callbacks/save_callback.py

@@ -27,15 +27,17 @@
 class SaveSubFormat(Enum):
     """Save Sub-Format enum."""
 
-    TF = "tf"
-    H5 = "h5"
+    TF = "tf"  #: TensorFlow format
+    H5 = "h5"  #: H5 Format
 
 
 class SaveFormat(Flag):
     """Save Format enum."""
 
-    WEIGHTS = auto()
-    MODEL = auto()
+    WEIGHTS = auto()  #: Weights format, saved using `model.save_weights()`
+    MODEL = (
+        auto()
+    )  #: Model format (weights and architecture), saved using `model.save()`
 
     def name(self) -> str:
         """Name of the format."""