Improving the documentations (#547)

* basic doc format corrections

* revise applications docs

* revise distribute docs

* updated tuners

* update the rest of the docstrings

* minor fixes to the docstrings

* addressing the comments

Co-authored-by: Haifeng Jin <haifeng-jin@users.noreply.github.com>

keras_tuner/applications/augment.py

@@ -36,14 +36,17 @@
 
 
 class HyperImageAugment(hypermodel.HyperModel):
- """Builds HyperModel for image augmentation.
+ """A image augmentation hypermodel.
 
- Only supporting augmentations available in Keras preprocessing layers currently.
+ The `HyperImageAugment` class searches for the best combination of image
+ augmentation operations in Keras preprocessing layers. The input shape of
+ the model should be (height, width, channels). The output of the model is
+ of the same shape as the input.
 
- Arguments:
+ Args:
  input_shape: Optional shape tuple, e.g. `(256, 256, 3)`.
- input_tensor: Optional Keras tensor (i.e. output of
- `layers.Input()`) to use as image input for the model.
+ input_tensor: Optional Keras tensor (i.e. output of `layers.Input()`)
+ to use as image input for the model.
  rotate: A number between [0, 1], a list of two numbers between [0, 1]
  or None. Configures the search space of the factor of random
  rotation transform in the augmentation. A factor is chosen for each
@@ -85,8 +88,8 @@ class HyperImageAugment(hypermodel.HyperModel):
  determines number of layers of augment transforms are applied,
  each randomly picked from all available transform types with equal
  probability on each sample.
- **kwargs: Additional keyword arguments that apply to all
- HyperModels. See `keras_tuner.HyperModel`.
+ **kwargs: Additional keyword arguments that apply to all hypermodels.
+ See `keras_tuner.HyperModel`.
 
  Example:
 
@@ -231,8 +234,9 @@ def _build_fixedaug_layers(self, inputs, hp):
 
  def _register_transform(self, transform_name, transform_params):
  """Register a transform and format parameters for tuning the transform.
- Arguments:
- transform_name: str, the name of the transform.
+
+ Args:
+ transform_name: A string, the name of the transform.
  trnasform_params: A number between [0, 1], a list of two numbers
  between [0, 1] or None. If set to a single number x, the
  corresponding transform factor will be between [0, x].

keras_tuner/applications/efficientnet.py

@@ -46,26 +46,25 @@
 
 
 class HyperEfficientNet(hypermodel.HyperModel):
- """An EfficientNet HyperModel.
-
- Models built by this HyperModel takes input image data in
- ints [0, 255]. The output data should be one-hot encoded
- with number of classes matching `classes`.
-
- Arguments:
- input_shape: shape tuple, e.g. `(256, 256, 3)`.
- Input images will be resized if different from
- the default input size of the version of
- efficientnet base model used.
- One of `input_shape` or `input_tensor` must be
- specified.
- input_tensor: Keras tensor to use as image input for the model.
- One of `input_shape` or `input_tensor` must be
- specified.
- classes: number of classes to classify images into.
- augmentation_model: optional Model or HyperModel for image augmentation.
- **kwargs: Additional keyword arguments that apply to all
- HyperModels. See `keras_tuner.HyperModel`.
+ """An EfficientNet hypermodel.
+
+ Models built by `HyperEfficientNet` take images with shape (height, width,
+ channels) as input. The output are one-hot encoded with the length matching
+ the number of classes specified by the `classes` argument.
+
+ Args:
+ input_shape: Optional shape tuple, e.g. `(256, 256, 3)`. One of
+ `input_shape` or `input_tensor` must be specified.
+ input_tensor: Optional Keras tensor (i.e. output of `layers.Input()`)
+ to use as image input for the model. One of `input_shape` or
+ `input_tensor` must be specified.
+ classes: Optional number of classes to classify images into, only to be
+ specified if `include_top` is True, and if no `weights` argument is
+ specified.
+ augmentation_model: Optional `Model` or `HyperModel` instance for image
+ augmentation.
+ **kwargs: Additional keyword arguments that apply to all hypermodels.
+ See `keras_tuner.HyperModel`.
  """
 
  def __init__(
@@ -81,7 +80,7 @@ def __init__(
  ):
  raise ValueError(
  "Keyword augmentation_model should be "
- "a HyperModel, a Keras Model or empty. "
+ "a `HyperModel`, a Keras `Model` or empty. "
  "Received {}.".format(augmentation_model)
  )
 
@@ -153,8 +152,8 @@ def build(self, hp):
  def _compile(self, model, hp):
  """Compile model using hyperparameters in hp.
 
- When subclassing the hypermodel, this may
- be overriden to change behavior of compiling.
+ When subclassing the hypermodel, this may be overriden to change
+ behavior of compiling.
  """
  learning_rate = hp.Choice("learning_rate", [0.1, 0.01, 0.001], default=0.01)
  optimizer = tf.keras.optimizers.SGD(

keras_tuner/applications/resnet.py

@@ -23,23 +23,25 @@
 
 
 class HyperResNet(hypermodel.HyperModel):
- """A ResNet HyperModel.
-
- Arguments:
- include_top: whether to include the fully-connected
- layer at the top of the network.
- input_shape: Optional shape tuple, e.g. `(256, 256, 3)`.
- One of `input_shape` or `input_tensor` must be
- specified.
- input_tensor: Optional Keras tensor (i.e. output of
- `layers.Input()`) to use as image input for the model.
- One of `input_shape` or `input_tensor` must be
- specified.
- classes: optional number of classes to classify images
- into, only to be specified if `include_top` is True,
- and if no `weights` argument is specified.
- **kwargs: Additional keyword arguments that apply to all
- HyperModels. See `keras_tuner.HyperModel`.
+ """A ResNet hypermodel.
+
+ Models built by `HyperResNet` take images with shape (height, width,
+ channels) as input. The output are one-hot encoded with the length matching
+ the number of classes specified by the `classes` argument.
+
+ Args:
+ include_top: Boolean, whether to include the fully-connected layer at
+ the top of the network.
+ input_shape: Optional shape tuple, e.g. `(256, 256, 3)`. One of
+ `input_shape` or `input_tensor` must be specified.
+ input_tensor: Optional Keras tensor (i.e. output of `layers.Input()`)
+ to use as image input for the model. One of `input_shape` or
+ `input_tensor` must be specified.
+ classes: Optional number of classes to classify images into, only to be
+ specified if `include_top` is True, and if no `weights` argument is
+ specified.
+ **kwargs: Additional keyword arguments that apply to all hypermodels.
+ See `keras_tuner.HyperModel`.
  """
 
  def __init__(
@@ -147,15 +149,17 @@ def build(self, hp):
 
 def block1(x, filters, kernel_size=3, stride=1, conv_shortcut=True, name=None):
  """A residual block.
- # Arguments
+
+ Args:
  x: input tensor.
  filters: integer, filters of the bottleneck layer.
  kernel_size: default 3, kernel size of the bottleneck layer.
  stride: default 1, stride of the first layer.
  conv_shortcut: default True, use convolution shortcut if True,
  otherwise identity shortcut.
  name: string, block label.
- # Returns
+
+ Returns:
  Output tensor for the residual block.
  """
  bn_axis = 3 if backend.image_data_format() == "channels_last" else 1
@@ -195,7 +199,7 @@ def block1(x, filters, kernel_size=3, stride=1, conv_shortcut=True, name=None):
 def stack1(x, filters, blocks, stride1=2, name=None):
  """A set of stacked residual blocks.
 
- Arguments:
+ Args:
  x: input tensor.
  filters: integer, filters of the bottleneck layer in a block.
  blocks: integer, blocks in the stacked blocks.
@@ -214,7 +218,7 @@ def stack1(x, filters, blocks, stride1=2, name=None):
 def block2(x, filters, kernel_size=3, stride=1, conv_shortcut=False, name=None):
  """A residual block.
 
- Arguments:
+ Args:
  x: input tensor.
  filters: integer, filters of the bottleneck layer.
  kernel_size: default 3, kernel size of the bottleneck layer.
@@ -265,7 +269,7 @@ def block2(x, filters, kernel_size=3, stride=1, conv_shortcut=False, name=None):
 def stack2(x, filters, blocks, stride1=2, name=None):
  """A set of stacked residual blocks.
 
- Arguments:
+ Args:
  x: input tensor.
  filters: integer, filters of the bottleneck layer in a block.
  blocks: integer, blocks in the stacked blocks.
@@ -287,7 +291,7 @@ def block3(
 ):
  """A residual block.
 
- Arguments:
+ Args:
  x: input tensor.
  filters: integer, filters of the bottleneck layer.
  kernel_size: default 3, kernel size of the bottleneck layer.
@@ -365,7 +369,7 @@ def block3(
 def stack3(x, filters, blocks, stride1=2, groups=32, name=None):
  """A set of stacked residual blocks.
 
- Arguments:
+ Args:
  x: input tensor.
  filters: integer, filters of the bottleneck layer in a block.
  blocks: integer, blocks in the stacked blocks.

keras_tuner/applications/xception.py

@@ -20,23 +20,25 @@
 
 
 class HyperXception(hypermodel.HyperModel):
- """An Xception HyperModel.
-
- Arguments:
- include_top: whether to include the fully-connected
- layer at the top of the network.
- input_shape: Optional shape tuple, e.g. `(256, 256, 3)`.
- One of `input_shape` or `input_tensor` must be
- specified.
- input_tensor: Optional Keras tensor (i.e. output of
- `layers.Input()`) to use as image input for the model.
- One of `input_shape` or `input_tensor` must be
- specified.
- classes: optional number of classes to classify images
- into, only to be specified if `include_top` is True,
- and if no `weights` argument is specified.
- **kwargs: Additional keyword arguments that apply to all
- HyperModels. See `keras_tuner.HyperModel`.
+ """An Xception hypermodel.
+
+ Models built by `HyperXception` take images with shape (height, width,
+ channels) as input. The output are one-hot encoded with the length matching
+ the number of classes specified by the `classes` argument.
+
+ Args:
+ include_top: Boolean, whether to include the fully-connected layer at
+ the top of the network.
+ input_shape: Optional shape tuple, e.g. `(256, 256, 3)`. One of
+ `input_shape` or `input_tensor` must be specified.
+ input_tensor: Optional Keras tensor (i.e. output of `layers.Input()`)
+ to use as image input for the model. One of `input_shape` or
+ `input_tensor` must be specified.
+ classes: Optional number of classes to classify images into, only to be
+ specified if `include_top` is True, and if no `weights` argument is
+ specified.
+ **kwargs: Additional keyword arguments that apply to all hypermodels.
+ See `keras_tuner.HyperModel`.
  """
 
  def __init__(

keras_tuner/distribute/utils.py

@@ -23,11 +23,11 @@
 def has_chief_oracle():
  """Checks for distributed tuning with a chief Oracle.
 
- `CloudOracle` manages its own distribution and so should not set
- "KERASTUNER_ORACLE_IP"
+ `CloudOracle` manages its own distribution so should not set
+ "KERASTUNER_ORACLE_IP".
 
  Returns:
- bool. Whether distributed tuning with a chief Oracle should be run.
+  Boolean, whether distributed tuning with a chief Oracle should be run.
  """
  if "KERASTUNER_ORACLE_IP" in os.environ:
  if "KERASTUNER_ORACLE_PORT" not in os.environ: